Paul BakausandClaude Opus 4.6 268a5e15cc Clarify context gathering protocol: session cache, no truncation, exceptions ...

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) <noreply@anthropic.com>

2026-04-14 08:54:38 -07:00

..

skills/impeccable

Clarify context gathering protocol: session cache, no truncation, exceptions

2026-04-14 08:54:38 -07:00