From 268a5e15cc0178e272e7eeacc896113bd7ad9e0f Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Tue, 14 Apr 2026 08:54:38 -0700 Subject: [PATCH] Clarify context gathering protocol: session cache, no truncation, exceptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two observed failure modes: 1. Smoke-test style truncation (`| head -N`) in bash commands defeats the whole point of load-context.mjs — Claude needs the FULL file contents, not the first few lines of JSON. 2. The old protocol didn't clearly explain session caching, leading to repeated load-context.mjs calls across commands in the same session (thousands of wasted tokens on 3-5KB files re-fetched 3-5 times). Context Gathering Protocol rewrite: - PRODUCT.md required (blocker), DESIGN.md optional (one-line nudge if missing). Greenfield projects can't yet have a DESIGN.md to document. - Explicit session cache: if content is in conversation history, do not re-fetch. Exceptions listed (after teach/document/manual edit). - Explicit "never truncate" rule: consume the full load-context.mjs output, never pipe through head/tail/grep/jq with field filters. - Content validity check: hasProduct=true but content <200 chars or full of [TODO] markers = treat as missing, run teach. - Missing-PRODUCT.md flow spells out task resumption: user asked for /impeccable polish ButtonGroup, we must run teach, then RESUME polish of ButtonGroup with fresh context — not silently abandon intent. - Three explicit exceptions to the protocol: - /impeccable teach skips it (teach creates PRODUCT.md) - /impeccable document loads PRODUCT.md only (creates DESIGN.md) - /impeccable live already warms context via live.mjs — don't also run load-context.mjs teach.md Step 6 and document.md Step 5 now re-run load-context.mjs at the end so the freshly-written files surface in conversation history and subsequent commands use the new version, not a stale earlier read. Co-Authored-By: Claude Opus 4.6 (1M context) --- .agents/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ .agents/skills/impeccable/reference/teach.md | 4 ++ .claude/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ .claude/skills/impeccable/reference/teach.md | 4 ++ .cursor/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ .cursor/skills/impeccable/reference/teach.md | 4 ++ .gemini/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ .gemini/skills/impeccable/reference/teach.md | 4 ++ .github/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ .github/skills/impeccable/reference/teach.md | 4 ++ .kiro/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .kiro/skills/impeccable/reference/document.md | 6 ++ .kiro/skills/impeccable/reference/teach.md | 4 ++ .opencode/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ .../skills/impeccable/reference/teach.md | 4 ++ .pi/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .pi/skills/impeccable/reference/document.md | 6 ++ .pi/skills/impeccable/reference/teach.md | 4 ++ .rovodev/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ .rovodev/skills/impeccable/reference/teach.md | 4 ++ .trae-cn/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ .trae-cn/skills/impeccable/reference/teach.md | 4 ++ .trae/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .trae/skills/impeccable/reference/document.md | 6 ++ .trae/skills/impeccable/reference/teach.md | 4 ++ source/skills/impeccable/SKILL.md | 57 ++++++++++++++----- .../skills/impeccable/reference/document.md | 6 ++ source/skills/impeccable/reference/teach.md | 4 ++ 36 files changed, 624 insertions(+), 180 deletions(-) diff --git a/.agents/skills/impeccable/SKILL.md b/.agents/skills/impeccable/SKILL.md index 66520b836..970bc2e1c 100644 --- a/.agents/skills/impeccable/SKILL.md +++ b/.agents/skills/impeccable/SKILL.md @@ -23,28 +23,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `$impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `$impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `$impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`$impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`$impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`$impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `$impeccable polish`, then `$impeccable audit`, then `$impeccable layout` without re-reading context files three times. --- diff --git a/.agents/skills/impeccable/reference/document.md b/.agents/skills/impeccable/reference/document.md index 626776da9..6b3e78d1d 100644 --- a/.agents/skills/impeccable/reference/document.md +++ b/.agents/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.agents/skills/impeccable/reference/teach.md b/.agents/skills/impeccable/reference/teach.md index 9d3c7e4a9..867012e83 100644 --- a/.agents/skills/impeccable/reference/teach.md +++ b/.agents/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `$impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.claude/skills/impeccable/SKILL.md b/.claude/skills/impeccable/SKILL.md index dce25b9d1..7bf4675b9 100644 --- a/.claude/skills/impeccable/SKILL.md +++ b/.claude/skills/impeccable/SKILL.md @@ -29,28 +29,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.claude/skills/impeccable/reference/document.md b/.claude/skills/impeccable/reference/document.md index f94dae564..585352ee8 100644 --- a/.claude/skills/impeccable/reference/document.md +++ b/.claude/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.claude/skills/impeccable/reference/teach.md b/.claude/skills/impeccable/reference/teach.md index 0e7f815c9..0c2ceea24 100644 --- a/.claude/skills/impeccable/reference/teach.md +++ b/.claude/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally STOP and call the AskUserQuestion tool to clarify. whether they'd like a brief summary of PRODUCT.md appended to CLAUDE.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.cursor/skills/impeccable/SKILL.md b/.cursor/skills/impeccable/SKILL.md index eae8b86e5..346d044c9 100644 --- a/.cursor/skills/impeccable/SKILL.md +++ b/.cursor/skills/impeccable/SKILL.md @@ -25,28 +25,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.cursor/skills/impeccable/reference/document.md b/.cursor/skills/impeccable/reference/document.md index 091ab1479..b59b8ac8b 100644 --- a/.cursor/skills/impeccable/reference/document.md +++ b/.cursor/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.cursor/skills/impeccable/reference/teach.md b/.cursor/skills/impeccable/reference/teach.md index a78f4059b..24fc9b9b3 100644 --- a/.cursor/skills/impeccable/reference/teach.md +++ b/.cursor/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to .cursorrules for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.gemini/skills/impeccable/SKILL.md b/.gemini/skills/impeccable/SKILL.md index aa1a08169..c4395133d 100644 --- a/.gemini/skills/impeccable/SKILL.md +++ b/.gemini/skills/impeccable/SKILL.md @@ -24,28 +24,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.gemini/skills/impeccable/reference/document.md b/.gemini/skills/impeccable/reference/document.md index 091ab1479..b59b8ac8b 100644 --- a/.gemini/skills/impeccable/reference/document.md +++ b/.gemini/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.gemini/skills/impeccable/reference/teach.md b/.gemini/skills/impeccable/reference/teach.md index ec35593f9..d754f5605 100644 --- a/.gemini/skills/impeccable/reference/teach.md +++ b/.gemini/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to GEMINI.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.github/skills/impeccable/SKILL.md b/.github/skills/impeccable/SKILL.md index 404bffa38..37c9f2946 100644 --- a/.github/skills/impeccable/SKILL.md +++ b/.github/skills/impeccable/SKILL.md @@ -27,28 +27,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.github/skills/impeccable/reference/document.md b/.github/skills/impeccable/reference/document.md index 091ab1479..b59b8ac8b 100644 --- a/.github/skills/impeccable/reference/document.md +++ b/.github/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.github/skills/impeccable/reference/teach.md b/.github/skills/impeccable/reference/teach.md index 8d0fdf14a..2a1eef65e 100644 --- a/.github/skills/impeccable/reference/teach.md +++ b/.github/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to .github/copilot-instructions.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.kiro/skills/impeccable/SKILL.md b/.kiro/skills/impeccable/SKILL.md index 6d27dd679..acfc8fa00 100644 --- a/.kiro/skills/impeccable/SKILL.md +++ b/.kiro/skills/impeccable/SKILL.md @@ -25,28 +25,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.kiro/skills/impeccable/reference/document.md b/.kiro/skills/impeccable/reference/document.md index 091ab1479..b59b8ac8b 100644 --- a/.kiro/skills/impeccable/reference/document.md +++ b/.kiro/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.kiro/skills/impeccable/reference/teach.md b/.kiro/skills/impeccable/reference/teach.md index 5b89def79..042311877 100644 --- a/.kiro/skills/impeccable/reference/teach.md +++ b/.kiro/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to .kiro/settings.json for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.opencode/skills/impeccable/SKILL.md b/.opencode/skills/impeccable/SKILL.md index f6db8c6c6..3c6c0f860 100644 --- a/.opencode/skills/impeccable/SKILL.md +++ b/.opencode/skills/impeccable/SKILL.md @@ -29,28 +29,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.opencode/skills/impeccable/reference/document.md b/.opencode/skills/impeccable/reference/document.md index 789f14800..f983beba8 100644 --- a/.opencode/skills/impeccable/reference/document.md +++ b/.opencode/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.opencode/skills/impeccable/reference/teach.md b/.opencode/skills/impeccable/reference/teach.md index 86289f443..e14dafe31 100644 --- a/.opencode/skills/impeccable/reference/teach.md +++ b/.opencode/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally STOP and call the `question` tool to clarify. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.pi/skills/impeccable/SKILL.md b/.pi/skills/impeccable/SKILL.md index ea013a9bb..15977d930 100644 --- a/.pi/skills/impeccable/SKILL.md +++ b/.pi/skills/impeccable/SKILL.md @@ -27,28 +27,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.pi/skills/impeccable/reference/document.md b/.pi/skills/impeccable/reference/document.md index 091ab1479..b59b8ac8b 100644 --- a/.pi/skills/impeccable/reference/document.md +++ b/.pi/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.pi/skills/impeccable/reference/teach.md b/.pi/skills/impeccable/reference/teach.md index b436efa20..c31ce2222 100644 --- a/.pi/skills/impeccable/reference/teach.md +++ b/.pi/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.rovodev/skills/impeccable/SKILL.md b/.rovodev/skills/impeccable/SKILL.md index e7bf70350..7be43ef7b 100644 --- a/.rovodev/skills/impeccable/SKILL.md +++ b/.rovodev/skills/impeccable/SKILL.md @@ -29,28 +29,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.rovodev/skills/impeccable/reference/document.md b/.rovodev/skills/impeccable/reference/document.md index 091ab1479..b59b8ac8b 100644 --- a/.rovodev/skills/impeccable/reference/document.md +++ b/.rovodev/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.rovodev/skills/impeccable/reference/teach.md b/.rovodev/skills/impeccable/reference/teach.md index b436efa20..c31ce2222 100644 --- a/.rovodev/skills/impeccable/reference/teach.md +++ b/.rovodev/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.trae-cn/skills/impeccable/SKILL.md b/.trae-cn/skills/impeccable/SKILL.md index 85d38949c..28ca342b9 100644 --- a/.trae-cn/skills/impeccable/SKILL.md +++ b/.trae-cn/skills/impeccable/SKILL.md @@ -27,28 +27,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.trae-cn/skills/impeccable/reference/document.md b/.trae-cn/skills/impeccable/reference/document.md index 091ab1479..b59b8ac8b 100644 --- a/.trae-cn/skills/impeccable/reference/document.md +++ b/.trae-cn/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.trae-cn/skills/impeccable/reference/teach.md b/.trae-cn/skills/impeccable/reference/teach.md index aef07b2be..afaaa3f18 100644 --- a/.trae-cn/skills/impeccable/reference/teach.md +++ b/.trae-cn/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to RULES.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/.trae/skills/impeccable/SKILL.md b/.trae/skills/impeccable/SKILL.md index 9b91dd82c..39e59a3c5 100644 --- a/.trae/skills/impeccable/SKILL.md +++ b/.trae/skills/impeccable/SKILL.md @@ -27,28 +27,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/.trae/skills/impeccable/reference/document.md b/.trae/skills/impeccable/reference/document.md index 091ab1479..b59b8ac8b 100644 --- a/.trae/skills/impeccable/reference/document.md +++ b/.trae/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/.trae/skills/impeccable/reference/teach.md b/.trae/skills/impeccable/reference/teach.md index aef07b2be..afaaa3f18 100644 --- a/.trae/skills/impeccable/reference/teach.md +++ b/.trae/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally ask the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to RULES.md for easier agent reference. If yes, append a short **Design Context** pointer section there. diff --git a/source/skills/impeccable/SKILL.md b/source/skills/impeccable/SKILL.md index 2398361a6..85267b36d 100644 --- a/source/skills/impeccable/SKILL.md +++ b/source/skills/impeccable/SKILL.md @@ -28,28 +28,55 @@ After running the script, delete this entire section (from `200 chars, no `[TODO]` placeholders): + - If `hasDesign: true`: proceed. You have full context. + - If `hasDesign: false`: do a one-line nudge to the user (say it once per session): *"Note: no DESIGN.md found. I'll use impeccable's built-in design principles. For more on-brand output, run `/impeccable document` to generate a DESIGN.md from your existing code."* Then proceed. +- **`hasProduct: false`** OR the file exists but is empty / full of `[TODO]` placeholders: + 1. Tell the user: *"I need PRODUCT.md before I can do this well. Running `/impeccable teach` now — I'll resume `[original task]` after."* + 2. Run `/impeccable teach`. + 3. When teach completes, re-run `load-context.mjs` and resume the **original** task the user asked for. Do not silently abandon intent. + +### Exceptions (commands that skip or reshape the protocol) + +- **`/impeccable teach`**: skips this protocol entirely — teach is how PRODUCT.md (and optionally DESIGN.md) get CREATED. Don't try to load before you create. +- **`/impeccable document`**: load PRODUCT.md (voice input) but do NOT block on missing DESIGN.md — document is how DESIGN.md gets created. +- **`/impeccable live`**: `live.mjs` already invokes the loader internally and returns both files in its startup JSON. When you've run `live.mjs`, the context is warmed. Do NOT additionally run `load-context.mjs` in the same session. + +### Why this matters + +- **Generic output is the #1 failure mode** of impeccable without PRODUCT.md. The user asked for polish and got a stock-looking polish because Claude had no tone to polish toward. +- **Warmed live sessions feel instant** because when the user finally clicks Generate in the browser, Claude already has PRODUCT + DESIGN in context and proceeds straight to variant generation. +- **Token-efficient sessions** let the user run `/impeccable polish`, then `/impeccable audit`, then `/impeccable layout` without re-reading context files three times. --- diff --git a/source/skills/impeccable/reference/document.md b/source/skills/impeccable/reference/document.md index 2535db2ba..ec78c560c 100644 --- a/source/skills/impeccable/reference/document.md +++ b/source/skills/impeccable/reference/document.md @@ -166,6 +166,12 @@ Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — i - **Don't** [...] ``` +### Step 5: Confirm, refine, and refresh session cache + +1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). +2. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" +3. **Refresh the session cache.** Run `node {{scripts_path}}/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. + ## Style guidelines - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). diff --git a/source/skills/impeccable/reference/teach.md b/source/skills/impeccable/reference/teach.md index 2d0c1488c..0a24438ef 100644 --- a/source/skills/impeccable/reference/teach.md +++ b/source/skills/impeccable/reference/teach.md @@ -101,4 +101,8 @@ Summarize: - The 3-5 strategic principles from PRODUCT.md that will guide future work - If DESIGN.md is pending, remind the user how to generate it later +**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node {{scripts_path}}/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version. + +If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context. + Optionally {{ask_instruction}} whether they'd like a brief summary of PRODUCT.md appended to {{config_file}} for easier agent reference. If yes, append a short **Design Context** pointer section there.