From 9b677ebf90e082a54cc28b4f9d44f3d19a0df175 Mon Sep 17 00:00:00 2001 From: mhenrixon Date: Sun, 5 Jul 2026 14:54:10 +0200 Subject: [PATCH 1/2] chore(claude): add unknowns-discovery phases to /plan and /lfg /plan gains a "Surface the unknowns" phase: a blindspot pass plus a one-question-at-a-time AskUserQuestion interview before design, with answers recorded as "Settled in interview" constraints in the plan. /lfg gains a deviation log (implementation-notes.md, folded into a mandatory "Deviations & judgment calls" PR-body section) and a comprehension close-out (key decisions + three merge-gate questions). Rationale: catch unknowns before execution in discovery loops, instead of after execution in review-fix loops. --- .claude/commands/lfg.md | 26 ++++++++++++++++++++++++++ .claude/commands/plan.md | 23 +++++++++++++++++++---- 2 files changed, 45 insertions(+), 4 deletions(-) diff --git a/.claude/commands/lfg.md b/.claude/commands/lfg.md index bacaca0..9c92d51 100644 --- a/.claude/commands/lfg.md +++ b/.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. diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md index 08149d6..3db6c01 100644 --- a/.claude/commands/plan.md +++ b/.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 | md | " -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 @@ -38,7 +38,21 @@ Protect this session's context: delegate mechanical exploration to cheaper subag - 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 3 — 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 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 ## Decision - + ## Implementation steps @@ -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-.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. From 180b78918c62005dd83bf0370cc0dc1960dd1b29 Mon Sep 17 00:00:00 2001 From: mhenrixon Date: Sun, 5 Jul 2026 14:56:25 +0200 Subject: [PATCH 2/2] =?UTF-8?q?chore(claude):=20interview=20before=20desig?= =?UTF-8?q?n=20=E2=80=94=20fix=20unknowns=20phase=20ordering?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Surface the unknowns" phase landed after Design; the interview must settle open decisions BEFORE candidate approaches are developed. Now Phase 2 (unknowns) precedes Phase 3 (Design), matching the other repos. --- .claude/commands/plan.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md index 3db6c01..60f15d7 100644 --- a/.claude/commands/plan.md +++ b/.claude/commands/plan.md @@ -32,13 +32,7 @@ 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 - -- 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 — Surface the unknowns (blindspot pass + interview) +## 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. @@ -52,6 +46,12 @@ Investigation tells you what the codebase says; this phase finds what the REQUES - 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 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.