Distills what a change accomplishes and why it looks the way it does into minimal, cold-rebuild-complete spec packs under docs/specs/<layer>/<pack>.md and append-only entries in docs/decisions.jsonl, ready for human review or automated verification via verify-deploy.
It splits ground truth across two sources and never invents claims from imagination:
- Code / Diff = Ground truth for what happens
- Conversation Transcript = Ground truth for why it happens
Per change, this skill updates only the impacted files:
docs/specs/<layer>/<pack>.md— Incrementedversion,## Intent,## Invariants,## Acceptance Criteria(**[kebab-slug]**), tight## Implementation Notes(only load-bearing SDK/platform traps),## Verification, and## Open Callouts.docs/decisions.jsonl— Append-only Distilled Decisions (D-1..N) withtype,outcome,authorcredit,packs,summary,resolution, and chronological 1st-person comments (no duplicate prose decisions or learnings files).
External Standards Protection: Never edit docs/standards/*.md during normal spec-extract runs. If local code intentionally diverges from an inherited standard rule, record a person-authored decision in docs/decisions.jsonl and declare an overrides: block in the owning docs/specs/<layer>/<pack>.md (or use spec-refactor to explicitly pull, update, or promote standards).
Step 1: Bootstrap (If Needed) & Read Ground-Truth Inputs
Run this skill's bundled validator (scripts/check-specs.ts alongside this SKILL.md) against the target repository ("$PWD"):
- Bootstrap Missing
docs/Structure:- If
docs/INDEX.mdordocs/decisions.jsonldoes not exist yet in the repository, initialize them non-destructively first:node --experimental-strip-types <this-skill-dir>/scripts/check-specs.ts --root "$PWD" --init
- If
- The Code & Working Tree:
- Inspect
git statusandgit diff(git diff <base>..HEADon feature branches). For stacked branches, diff each branch against its immediate parent. - If Git is uninitialized or has no commits yet, inspect the project tree, configuration, tests, and implementation files directly.
- Inspect
- The Conversation Transcript:
- Read the active conversation history and any session transcript logs on disk when earlier turns were compacted or summarized.
- Current Specs & Effective Rules:
- Read
docs/INDEX.md, impacted packs underdocs/specs/, recent lines ofdocs/decisions.jsonl, and resolve the active ruleset:node --experimental-strip-types <this-skill-dir>/scripts/check-specs.ts --root "$PWD" --effective --json - Map changed files to the existing conceptual pack(s). Do not create redundant packs or re-layer unless the change introduces a genuinely distinct domain boundary (use
spec-refactorfor structural pack splits or merges).
- Read
Step 2: Distill Decisions (docs/decisions.jsonl)
Read references/decisions.md and apply its distillation, attribution, and thread rules to the transcript:
- Append Decisions (
D-...) todocs/decisions.jsonl: choices, intentional oddities, accepted risks, non-obvious fixed bugs, deferred follow-ups, withdrawn concerns, or answered/open questions where a reviewer could ask "why?" and the session answered. - Fold only load-bearing operational/SDK traps (facts required to build, configure, run, or avoid silent regressions — never session play-by-play) into the owning pack's
## Implementation Notessection.
Step 3: Update Owning Pack(s) (Intent, Acceptance Criteria, Verification, Callouts)
For each touched docs/specs/<layer>/<pack>.md:
- Intent:
- 1–3 plain sentences describing the pack's behavioral purpose, echoing the user's phrasing without internal class/file/table names.
- Invariants & Acceptance Criteria (
**[kebab-slug]**):- Read references/acceptance-criteria.md and enforce every gate (including cross-filtering against Step 2's Decisions).
- Keep 2–5 focused criteria per pack using stable kebab-case slugs (never numeric
AC-1orP1.1). Preserve existing slugs unless behavior changed; adding criteria in one pack must never evict criteria from other packs.
- Verification & Implementation Notes:
- Keep
## Verificationconcise and executable (read-only state/DB queries, CLI checks, UI checks, or isolatedmktemp -ddrills). - Keep
## Implementation Notesterse: record exact protocol/config contracts and SDK traps once, without narrative prose.
- Keep
- Open Callouts:
- Flag only what is genuinely open or contradictory (code failing a criterion, code diverging from an adopted standard without a ratified override, or an
opendecision).
- Flag only what is genuinely open or contradictory (code failing a criterion, code diverging from an adopted standard without a ratified override, or an
Step 4: Review with the User (Interactive Mode)
When running interactively for confirmation before writing (or when asked to preview first):
- Show impacted pack(s), Intent, Acceptance Criteria (noting each
[slug]is verified independently), Open Callouts, any needed standard Overrides, and the Decisions Preview. - Ask one direct question: "Anything to add, remove, or tighten before I persist these updates to
docs/?" - When the user explicitly asks to write/persist immediately, write directly and note that confirmation was pre-authorized.
Step 5: Persist & Validate
- Update only touched
docs/specs/<layer>/<pack>.mdfiles (incrementing integerversion). - Append new lines to
docs/decisions.jsonl(preserving existing lines verbatim). - Update
docs/INDEX.mdif a new pack was added so every pack has a relative Markdown link. - Validate schema, slug uniqueness, override authority, and index links before finishing:
node --experimental-strip-types <this-skill-dir>/scripts/check-specs.ts --root "$PWD" - Note that any rule whose exact text changed must be re-verified by
verify-deploy(prior waivers indocs/runs/do not carry forward across modified rule text).