From 36ef6e986929ab77b61d6a2655bc5f997e3c99bd Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Fri, 17 Apr 2026 05:55:08 +0800 Subject: [PATCH] feat: context health soft directive in preamble (T2+) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a "periodically self-summarize" nudge to long-running skills. Soft directive only — no thresholds, no enforcement, no auto-commit. Goal: self-awareness during /qa, /investigate, /cso etc. If you notice yourself going in circles, STOP and reassess instead of thrashing. Codex review caught that fake precision thresholds (15/30/45 tool calls) were unimplementable — SKILL.md is a static prompt, not runtime code. This ships the soft version only. Changes: - scripts/resolvers/preamble.ts: add generateContextHealth(), wire into T2+ tier. Format: [PROGRESS] ... summary line. Explicit rule that progress reporting must never mutate git state. - All T2+ skill SKILL.md files regenerated to include the new section. - Golden ship fixtures updated (T4 skill, picks up the change). Co-Authored-By: Claude Opus 4.7 (1M context) --- autoplan/SKILL.md | 15 +++++++++++++++ canary/SKILL.md | 15 +++++++++++++++ checkpoint/SKILL.md | 15 +++++++++++++++ codex/SKILL.md | 15 +++++++++++++++ cso/SKILL.md | 15 +++++++++++++++ design-consultation/SKILL.md | 15 +++++++++++++++ design-html/SKILL.md | 15 +++++++++++++++ design-review/SKILL.md | 15 +++++++++++++++ design-shotgun/SKILL.md | 15 +++++++++++++++ devex-review/SKILL.md | 15 +++++++++++++++ document-release/SKILL.md | 15 +++++++++++++++ health/SKILL.md | 15 +++++++++++++++ investigate/SKILL.md | 15 +++++++++++++++ land-and-deploy/SKILL.md | 15 +++++++++++++++ learn/SKILL.md | 15 +++++++++++++++ office-hours/SKILL.md | 15 +++++++++++++++ open-gstack-browser/SKILL.md | 15 +++++++++++++++ pair-agent/SKILL.md | 15 +++++++++++++++ plan-ceo-review/SKILL.md | 15 +++++++++++++++ plan-design-review/SKILL.md | 15 +++++++++++++++ plan-devex-review/SKILL.md | 15 +++++++++++++++ plan-eng-review/SKILL.md | 15 +++++++++++++++ qa-only/SKILL.md | 15 +++++++++++++++ qa/SKILL.md | 15 +++++++++++++++ retro/SKILL.md | 15 +++++++++++++++ review/SKILL.md | 15 +++++++++++++++ scripts/resolvers/preamble.ts | 19 ++++++++++++++++++- setup-deploy/SKILL.md | 15 +++++++++++++++ ship/SKILL.md | 15 +++++++++++++++ test/fixtures/golden/claude-ship-SKILL.md | 15 +++++++++++++++ test/fixtures/golden/codex-ship-SKILL.md | 15 +++++++++++++++ test/fixtures/golden/factory-ship-SKILL.md | 15 +++++++++++++++ 32 files changed, 483 insertions(+), 1 deletion(-) diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 7b05d620..038d9e05 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -383,6 +383,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/canary/SKILL.md b/canary/SKILL.md index 6cf76203..c2f0a089 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -375,6 +375,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/checkpoint/SKILL.md b/checkpoint/SKILL.md index 22b5d3ad..f0bf78b8 100644 --- a/checkpoint/SKILL.md +++ b/checkpoint/SKILL.md @@ -378,6 +378,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/codex/SKILL.md b/codex/SKILL.md index 9b40b27e..621c4ead 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/cso/SKILL.md b/cso/SKILL.md index 89f2b13f..6556a4b5 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index f717625a..ef3f144a 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/design-html/SKILL.md b/design-html/SKILL.md index 10aaece0..3e743a40 100644 --- a/design-html/SKILL.md +++ b/design-html/SKILL.md @@ -382,6 +382,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 9c404a23..e6ffe9f7 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index 95d5bab2..0628f8c7 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md index 96575fea..a59561d9 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/document-release/SKILL.md b/document-release/SKILL.md index 90b84d2d..7f2e4763 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/health/SKILL.md b/health/SKILL.md index f8f7b2ae..843dfb95 100644 --- a/health/SKILL.md +++ b/health/SKILL.md @@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/investigate/SKILL.md b/investigate/SKILL.md index 30feccd0..4f3a1a88 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -392,6 +392,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index 64402009..0fc3a443 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -374,6 +374,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/learn/SKILL.md b/learn/SKILL.md index 656ae76b..3c88385e 100644 --- a/learn/SKILL.md +++ b/learn/SKILL.md @@ -377,6 +377,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index bcb3557c..cdb813ae 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -384,6 +384,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/open-gstack-browser/SKILL.md b/open-gstack-browser/SKILL.md index 126bd5fb..7933cb48 100644 --- a/open-gstack-browser/SKILL.md +++ b/open-gstack-browser/SKILL.md @@ -374,6 +374,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index 6a7ddbbb..2983b2db 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -375,6 +375,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 78e87f4d..9d9045c0 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index 6003e81f..d199f40e 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -378,6 +378,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index 56a51ba2..c5537a97 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -382,6 +382,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 93f71bd7..2a04ab1e 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -380,6 +380,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index f1eeedff..0d4be44a 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -376,6 +376,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/qa/SKILL.md b/qa/SKILL.md index edb475c9..d60c41aa 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -382,6 +382,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/retro/SKILL.md b/retro/SKILL.md index b2f43419..711ae1c0 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -375,6 +375,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/review/SKILL.md b/review/SKILL.md index 9e2965db..14191488 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -378,6 +378,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/scripts/resolvers/preamble.ts b/scripts/resolvers/preamble.ts index bacbc0f0..4a40444b 100644 --- a/scripts/resolvers/preamble.ts +++ b/scripts/resolvers/preamble.ts @@ -704,6 +704,23 @@ are shown, synthesize a one-paragraph welcome briefing before proceeding: available]. [Health score if available]." Keep it to 2-3 sentences.`; } +function generateContextHealth(): string { + return `## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief \`[PROGRESS]\` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +\`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.\` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing.`; +} + // Preamble Composition (tier → sections) // ───────────────────────────────────────────── // T1: core + upgrade + lake + telemetry + voice(trimmed) + completion @@ -731,7 +748,7 @@ export function generatePreamble(ctx: TemplateContext): string { generateVendoringDeprecation(ctx), generateSpawnedSessionCheck(), generateVoiceDirective(tier), - ...(tier >= 2 ? [generateContextRecovery(ctx), generateAskUserFormat(ctx), generateCompletenessSection()] : []), + ...(tier >= 2 ? [generateContextRecovery(ctx), generateAskUserFormat(ctx), generateCompletenessSection(), generateContextHealth()] : []), ...(tier >= 3 ? [generateRepoModeSection(), generateSearchBeforeBuildingSection(ctx)] : []), generateCompletionStatus(ctx), ]; diff --git a/setup-deploy/SKILL.md b/setup-deploy/SKILL.md index 41ba613e..517af246 100644 --- a/setup-deploy/SKILL.md +++ b/setup-deploy/SKILL.md @@ -378,6 +378,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/ship/SKILL.md b/ship/SKILL.md index f3bfd626..8a0053ba 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -379,6 +379,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/test/fixtures/golden/claude-ship-SKILL.md b/test/fixtures/golden/claude-ship-SKILL.md index f3bfd626..8a0053ba 100644 --- a/test/fixtures/golden/claude-ship-SKILL.md +++ b/test/fixtures/golden/claude-ship-SKILL.md @@ -379,6 +379,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/test/fixtures/golden/codex-ship-SKILL.md b/test/fixtures/golden/codex-ship-SKILL.md index a08bf447..e472b39d 100644 --- a/test/fixtures/golden/codex-ship-SKILL.md +++ b/test/fixtures/golden/codex-ship-SKILL.md @@ -373,6 +373,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/test/fixtures/golden/factory-ship-SKILL.md b/test/fixtures/golden/factory-ship-SKILL.md index 2c6f33a8..d497a878 100644 --- a/test/fixtures/golden/factory-ship-SKILL.md +++ b/test/fixtures/golden/factory-ship-SKILL.md @@ -375,6 +375,21 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Context Health (soft directive) + +During long-running skill sessions, periodically write a brief `[PROGRESS]` summary +(2-3 sentences: what's done, what's next, any surprises). Example: + +`[PROGRESS] Found 3 auth bugs. Fixed 2. Remaining: session expiry race in auth.ts:147. Next: write regression test.` + +If you notice you're going in circles — repeating the same diagnostic, re-reading the +same file, or trying variants of a failed fix — STOP and reassess. Consider escalating +or calling /checkpoint to save progress and start fresh. + +This is a soft nudge, not a measurable feature. No thresholds, no enforcement. The +goal is self-awareness during long sessions. If the session stays short, skip it. +Progress summaries must NEVER mutate git state — they are reporting, not committing. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: