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..60f15d7 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 @@ -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 ## 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.