chore(claude): add unknowns-discovery phases to /plan and /lfg

.claude/commands/lfg.md

@@ -89,6 +89,16 @@ Create a TaskCreate todo list with specific implementation steps.
 
 ## Phase 4: Implement (TDD)
 
+### The deviation log (keep it from the first edit)
+
+The plan is the map; the codebase is the territory. The moment reality forces a choice the plan or issue didn't settle, log it in `implementation-notes.md` at the repo root — one line, at the moment it happens, not reconstructed later:
+
+- **Deviations** — the plan said X, you did Y, because Z
+- **Discoveries** — facts about the codebase the plan didn't know
+- **Judgment calls** — choices the user might have made differently (defaults, naming, scope cuts)
+
+Pick the conservative option and keep going. The log is how the user audits your judgment afterwards. Never commit the file: its contents move into the PR body, then the file is deleted.
+
 For each logical unit:
 
 ### 4.1: Write Failing Test First
@@ -230,6 +240,20 @@ Write the PR body to a temp file (`--body-file`) to avoid shell-interpolation of
 backticks/tables. The body is copied verbatim — if you would not type a
 backslash in a GitHub comment, do not type one in the heredoc.
 
+The PR body MUST end with a `## Deviations & judgment calls` section copied from
+`implementation-notes.md` (then delete the file). If the plan held completely,
+write "None — the plan held." This section is read FIRST in review — it is the
+audit trail for every decision the plan didn't make.
+
+---
+
+## Phase 8: Comprehension Close-Out
+
+The tests prove the CODE is right; this phase keeps the USER's mental model right. After the PR is up, end your final message with:
+
+1. **The decisions, not the diff** — the 3–5 non-obvious choices in this change someone must understand to maintain it. Lead with anything from the deviation log; the user has never seen those.
+2. **Three merge-gate questions** the user should be able to answer before merging. If any answer isn't obvious to them, offer a walkthrough — an unanswerable question is comprehension debt, and merging anyway is how it compounds.
+
 ---
 
 ## Verification Checklist
@@ -242,5 +266,7 @@ backslash in a GitHub comment, do not type one in the heredoc.
 - [ ] New setup wired into the install generator / `docs-kit new` template
 - [ ] CSS build scans any new emitted classes (`@source` updated if needed)
 - [ ] PR created with summary + test plan
+- [ ] PR body ends with `## Deviations & judgment calls` (from implementation-notes.md, since deleted)
+- [ ] Comprehension close-out delivered (decisions + three merge-gate questions)
 
 Now, execute this workflow for the provided issue or feature.

.claude/commands/plan.md

@@ -2,7 +2,7 @@
 description: "Investigates the codebase, designs a solution, and produces a durable plan artifact — a GitHub issue or a plan markdown under docs/plans/. Read-only: never edits application code. Use before /lfg for anything non-trivial."
 model: fable
 argument-hint: "issue <feature or problem> | md <feature or problem> | <feature or problem>"
-allowed-tools: Bash(gh issue create:*), Bash(gh issue list:*), Bash(gh issue view:*), Bash(gh search:*), Bash(gh label list:*), Bash(git log:*), Bash(git diff:*), Bash(git branch:*), Bash(date:*), Read, Grep, Glob, Write, Agent
+allowed-tools: Bash(gh issue create:*), Bash(gh issue list:*), Bash(gh issue view:*), Bash(gh search:*), Bash(gh label list:*), Bash(git log:*), Bash(git diff:*), Bash(git branch:*), Bash(date:*), Read, Grep, Glob, Write, Agent, AskUserQuestion
 ---
 
 # Plan — design expensive, execute cheap
@@ -32,13 +32,27 @@ Protect this session's context: delegate mechanical exploration to cheaper subag
 3. Read `CLAUDE.md` and the `.claude/rules/` files — the project invariants live there.
 4. Check `git log` for recent related work; the design should extend it, not fight it.
 
-## Phase 2 — Design
+## Phase 2 — Surface the unknowns (blindspot pass + interview)
+
+Investigation tells you what the codebase says; this phase finds what the REQUEST doesn't say. Run it BEFORE designing — a wrong assumption caught here costs one question; caught in review it costs a rewrite.
+
+1. **Blindspot pass.** Write down the unknowns you are carrying into the design:
+   - decisions the request leaves open (defaults, naming, public API/config surface, rollout & upgrade story)
+   - edge cases the codebase makes possible that the request never mentions
+   - anything with no precedent in this repo — flag it explicitly as unknown-unknown territory
+2. **Interview the user** with AskUserQuestion, one question at a time, prioritized by blast radius: architecture-changing answers first, then public API / config surface, then UX. Rules:
+   - Skip anything the codebase, CLAUDE.md, or an existing issue already answers.
+   - 2–5 questions is the sweet spot; zero is fine when the request is genuinely unambiguous — say so rather than inventing questions.
+   - Every question offers concrete options with a recommended default, never an open-ended essay prompt.
+3. **Record the answers** in the plan's Decision section as `Settled in interview:` bullets — constraints the executor must not re-litigate.
+
+## Phase 3 — Design
 
 - Develop 2–3 candidate approaches with real tradeoffs. Pick one and say why; record why the others lost.
 - The chosen design must respect docs-kit invariants: chrome is composed from `DocsUI::` Phlex components (never raw daisyUI markup); site-specific values come from `DocsKit.configuration` (with a default, for backwards compat); the page works with JavaScript off (progressive enhancement); there is exactly ONE Stimulus controller (`docs-nav`) — no per-feature JS; `config.themes` stays in sync with the Tailwind `@plugin` theme list; new emitted classes need a CSS `@source` scan; any required setup is wired into the install generator AND the `docs-kit new` template, not just the README; TDD (specs named before implementation steps).
 - Decide the test strategy per the testing rules: config specs for a new knob + its default, component-render specs for output/semantics, registry specs for grouping/lookup, generator specs for install output.
 
-## Phase 3 — Emit the plan artifact
+## Phase 4 — Emit the plan artifact
 
 Use this structure for the issue body or markdown file. Every section is load-bearing — an executor uses Context to avoid re-discovery, Steps to act, Gates to verify, Boundaries to stop.
 
@@ -52,7 +66,8 @@ Use this structure for the issue body or markdown file. Every section is load-be
 <Bullet list: `path/to/file.rb` — why it matters to this change. Include the config surface, the components, the registry, the engine, the generator templates. Self-contained: no references to "as discussed" or this session.>
 
 ## Decision
-<Chosen approach and rationale. Then: alternatives considered and why each was rejected.>
+<Chosen approach and rationale. Then: alternatives considered and why each was rejected.
+End with `Settled in interview:` bullets for every constraint the user confirmed in the interview phase — the executor must not re-litigate these.>
 
 ## Implementation steps
 <Ordered, small, each mapped to a layer where useful (config → registry → component → client → generator → CSS contract → docs). Specs come before the code they cover. Name exact files to create or change.>
@@ -75,6 +90,6 @@ For GitHub issues: create with `gh issue create --title "..." --body "$(cat <<'E
 
 For markdown files: Write to `docs/plans/YYYY-MM-DD-<slug>.md`. Leave it uncommitted — committing is the user's call.
 
-## Phase 4 — Handoff
+## Phase 5 — Handoff
 
 Report back: link to the issue (or file path), the chosen approach in 2–3 sentences, and the exact execute command. Stop there — do not start implementing.