git:20260823.e97a3b3 to git:20260901.a877ac0

- Builds and stress-tests implementation plans in two modes. Create mode scans

- code and docs, asks one question at a time with a recommended answer, runs a

- blindspot pass when the user is new to the area, then writes a plan file.

- Review mode scores completeness, feasibility, scope,

- testability, risk, and assumptions, verifies checkable claims, and writes

- resolutions back until every dimension reaches 5/5. Use when asked to "create

- a plan", "plan this feature", "I want to build X", "grill me", "think this

- through", "blindspot pass", "unknown unknowns", "this is new to me", "review

- my plan", "rubber duck this", "stress test this plan", "is

- this plan ready", "get this plan to 5/5", "what am I missing", "verify this

- claim", "prove this plan", "fact-check this plan", "split this into

- tickets", "break this down into slices", "this is too big for one plan", or

- when the user explicitly wants a plan artifact before implementation. For

- code review use pr-reviewer; for architecture briefs use

- codebase-architecture.

- Build a plan by collaborative interrogation, then stress-test it adversarially, before coding. The deliverable is a plan file, or the tickets that plan splits into when the work is too big for one pass. Never code.

- - **IS:** building a plan from intent through one-question-at-a-time interrogation (Create), and strengthening an existing plan by scoring six dimensions to 5/5 with claim verification (Review). Both write to the plan file. When the work exceeds one plan, both exit through the split in `references/splitting.md`, which publishes vertical-slice tickets.

- - **IS NOT:** implementing or generating code, authoring a PR (use `pr-creator`), reviewing a code diff (use `pr-reviewer`), or writing an architecture brief (use `codebase-architecture`).

- Pipeline position: `planning` (create then review) -> implementation -> `pr-reviewer` -> `pr-creator` -> `pr-babysitter`.

- - **No plan file in scope**, or verbs like "create a plan", "plan this", "grill me", "think this through" -> **Create mode**.

- - **Existing plan in scope** (a path, pasted plan, or recent file in the active agent's native plan directory), or verbs like "review my plan", "stress test", "is this ready", "get this to 5/5", "verify this claim", "fact-check this plan" -> **Review mode**.

- - **No plan in scope but the user asks to verify or fact-check a standalone claim** -> answer directly with local evidence; create no plan artifact.

- - If the input is code or a diff rather than a plan, stop and route to `pr-reviewer`.

- Use these to cut scope, sequence work, and challenge the plan. Turn each into a plan edit; never cite slogans.

- 1. **KISS:** fewest moving parts that satisfy the current requirement. Delete layers, modes, config, or coordination that do not change the first shippable outcome.

- 2. **As simple as possible, no simpler:** never cut correctness, permissions, observability, rollback, migration safety, or required edge states. A smaller plan that drops a current requirement is too small.

- 3. **YAGNI:** defer extension points, future providers, generic frameworks, and speculative settings until a named current requirement needs them.

- 4. **Proven practice:** when the ecosystem or repo has a proven pattern for this exact problem, use it and name the precedent. Invent a local pattern only when a concrete constraint makes the standard one fail.

- 5. **Easier to change:** make the next likely requirement local. Name what file, module, table, or API boundary changes later, and what stays untouched.

- 6. **Tracer bullet:** prove the approach with one minimum viable vertical slice across the real boundary before building horizontal layers.

- 7. **DRY:** deduplicate knowledge, invariants, protocols, and business rules, not coincidental shape.

- 8. **Duplication over wrong abstraction:** keep similar code duplicated when the shared abstraction would hide different business rules, lifecycles, owners, or failure modes.

- 9. **Ladder of least code:** for each piece of new code the plan calls for, take the first rung that holds: reuse what is already in the codebase, then stdlib, then a native platform feature, then an already-installed dependency, then the minimum new code. A plan step that adds a dependency, or new code a higher rung plausibly covers, must say why the higher rungs fail.

- Conflict rule: current requirements win first. Then `as simple as possible, no simpler` bounds KISS and YAGNI; `duplication over wrong abstraction` bounds DRY; `tracer bullet` beats horizontal foundation work unless the project cannot run without that foundation.

- | `references/interrogation-protocol.md` | Create | Create Step 2: question decision tree, blindspot pass, reference-as-spec, recommended-answer format, fuzzy-term patterns, anti-rationalization table |

- | `references/doc-grounding.md` | Create | Create Step 1, when design docs, RFCs, ADRs, or library/API docs are relevant: find them, extract the decisions they encode, grill the rationale |

- | `references/html-question-form.md` | Create | Create Step 2, optional: batched HTML question form for large or greenfield specs instead of one-at-a-time chat |

- | `references/plan-quality-rubric.md` | Review | Review Step 2 triage: 1-5 scoring criteria per dimension |

- | `references/dialogue-examples.md` | Review | Before the Review dialogue: tone calibration, and the Verify move's claim/evidence/verdict block worked through |

- | `references/splitting.md` | Both | The work is too big for one plan: vertical slice rules, blocking edges, the expand-contract exception, granularity confirmation, and how to publish the tickets |

- | `references/claim-verification.md` | Review | When a claim is checkable against local code, docs, or specs, or the user asks to verify one |

- - [ ] Step 2: Interrogate (one question at a time; end with the "radically simpler?" challenge)

- - [ ] Step 4: Validate (run the four checks, emit the validation block)

- Before asking, scan code and docs:

-

- - Identify modules, files, and patterns related to the request; note conventions, abstractions, boundaries, and prior art.

- - Read relevant design docs, RFCs, ADRs, READMEs, referenced library/API docs, and any spec the user points to. Load `references/doc-grounding.md` to find docs and extract their decisions and rationale.

-

- State findings in 2-3 sentences before the first question.

- Load `references/interrogation-protocol.md`. Ask ONE question at a time. Every question carries a **recommended answer** grounded in Step 1: name the file, function, approach.

-

- - **Diverge before converging (first move):** put 2-3 genuinely different framings of the work on the table, not variations on one, each with what it buys and what it forecloses, then recommend one. Every later question narrows, so this is the only turn where the frame itself is still open. It costs at most one question and catches the two scope errors nothing else does: too narrow (a one-line fix where the whole bug class needed handling) and too wide (a framework where one function held).

- - If code or docs can answer it, answer it yourself; never spend a user question on it.

- - Each answer shapes the next. Walk the decision tree: resolve intent and scope before approach, approach before risks.

- - Flag fuzzy terms ("handle auth", "make it fast"): propose a sharp version and ask if it is right.

- - Surface tensions with existing code: "The codebase does X. You're proposing Y. Which wins?"

- - **Grill the core decisions:** when docs reveal a decision, interrogate *why* it was made and whether the rationale still holds. Never re-ask what docs answer; pressure-test the reasoning.

- - **Probe for a reference-as-spec:** ask if existing code, a library, a design, or a site already does this the way the user wants. If so, read it and treat its semantics as the spec, interrogating only deviations.

- - **Blindspot pass (conditional):** when the user is unfamiliar with the area or asks for one ("blindspot pass", "unknown unknowns"), pause questions to surface what good looks like, prior work, and potholes, then teach it back before resuming. Detail in `references/interrogation-protocol.md`.

- **Budget:** 5-10 questions, then synthesize. Needing more than 10 is evidence the scope is too big for one plan; propose a split instead of continuing to ask, and load `references/splitting.md` to run it. A split redirects Step 3: the deliverable becomes the approved tickets, indexed by a `## Slices` section in a lightweight plan file, rather than one plan no executor can finish in a pass. Steps 4 and 5 still run on that file.

- **Mandatory scope challenge (before synthesizing):** ask "What can we cut without dropping a current requirement?" Carry a recommended cut list: removed extension points, setup collapsed into the first vertical slice, new code or dependencies a higher ladder rung already covers, abstractions kept only when they protect a shared invariant/owner/lifecycle, and safety gates preserved where "simpler" would drop correctness. Challenge the *sum* of the plan, not each piece.

- **Batch mode (optional):** for large or greenfield specs with many independent questions, generate one local HTML form. Load `references/html-question-form.md` for the template and batch-vs-sequential table. Default to one-at-a-time when answers should shape later questions.

- **Escape hatch:** if the user says "just write the plan", push back once via the anti-rationalization table, then respect their call and skip to Step 3.

- Write the plan file to the active agent's native plan directory when one exists; otherwise to the user-specified path or the repo-local plan location set by project instructions. Match format to scope.

- **Standard** (multiple files, decisions made): `# Title`, `## Context` (problem, what prompted it, intended outcome), `## Approach` (recommended only), `## Key decisions` (brief rationale), `## Files to modify` (grouped by purpose), `## Out of scope` (related-looking things that must not change, each with a reason), `## Verification` (each item a command plus expected result).

-

- **Order volatile-first:** within Approach, Key decisions, and Files to modify, lead with the decisions the user is most likely to tweak (data model changes, new type interfaces, user-facing flows) and sink mechanical refactoring detail to the bottom. A reviewer should be able to stop reading once the tweakable decisions look right.

-

- Keep plans scannable yet executable without re-reading the conversation. Record only the chosen approach; rejected alternatives become one-line rationale under Key decisions.

-

- **Size the plan to the work, not to the template.** Pick the lightest format the task supports, and drop any section the task does not need rather than filling it. A plan that restates the codebase, enumerates every file when a pattern plus three representative paths would do, or explains decisions the reader already made costs review attention and buries the parts that need a second look.

-

- **Handoff plans:** when another agent or session will execute, the executor has not seen this conversation. Inline any code excerpts and conventions it needs (with `file:line` markers), and add a **STOP conditions** section: assumptions that, if false, mean stop and report back rather than improvise.

- Name an implementation-notes file next to the plan and instruct the executor to keep it: every deviation the code forced on the plan gets logged under a `## Deviations` heading as what the plan said, what the code required, and which option was taken. A deviation that is not a STOP condition never pauses the work; take the conservative option, log it, keep going. The notes file is what review reads afterwards, so a handoff without one loses every decision made during execution.

- A handoff plan also says what an acceptable finish looks like, not only what trips a STOP. STOP conditions name assumptions checkable in advance; an executor that never trips one and has no finish line keeps patching past the point the work stopped converging. The last entry in the implementation-notes file states how the run ended and the evidence for it: the capability works on the real path and the case that motivated the plan improved, or a genuine blocker was removed and the next one isolated, or the run stopped because finishing would need scope the plan does not cover.

- - Does the plan answer the user's original request?

- - **Scope gate:** the plan fails if it violates any decision principle, especially an unneeded extension point, horizontal setup before the first tracer bullet, new code or a new dependency where a higher ladder rung holds, or a cut that drops required correctness, permissions, rollback, migration safety, or edge states.

- - Any unstated assumptions that should be explicit?

-

- Fix failures in the plan directly; don't reopen the interrogation.

- Then emit the validation block. Every row cites the plan section that satisfies its check, so a check with nothing to cite is a failure to fix before reporting rather than a claim to assert:

- Lightweight plans have no Verification section; cite the one check that proves the approach instead.

- Offer Review: "Plan written to `<path>`. Stress-test it to 5/5 before implementation?"

- **Objective:** drive all six dimensions to **5/5**. Work each sub-5 dimension upward, re-scoring each round, until all are 5/5 or provably stalled on a decision only the user can make.

- - [ ] Step 4: Re-score after each dimension; repeat the sweep until all 5/5 or stalled

- - [ ] Step 5: Gap summary (before/after scores + residual blockers)

- - [ ] Step 6: Confirm the plan file contains every resolution and unresolved annotation

- If the user gives a path, read it. Otherwise list the active agent's native plan directory by modification time, pick the most recent, and confirm. Read the full plan; note its goal, structure, length. If it is a diff or code, stop and route to `pr-reviewer`.

- Load `references/plan-quality-rubric.md`. Silently score each of the six dimensions 1-5. While scoring, mark every claim checkable against local code, docs, or specs; verify the load-bearing ones now (load `references/claim-verification.md`) and fold the verdicts into the scores. Never spend a dialogue turn on what the codebase can answer.

-

- Output a triage table:

- State: "I'll work each dimension up to 5/5, starting with the weakest." If more than 3 dimensions start at 1-2, the plan needs rewriting, not review: switch to Create mode instead of grinding the loop. If Scope stays below 5 because the plan carries more than one shippable outcome, it is two plans and no amount of tightening fixes that: split it with `references/splitting.md`.

- Load `references/questioning-framework.md` and `references/dialogue-examples.md`. Each round:

- 1. Pick the lowest-scoring dimension still below 5.

- 2. Ask ONE question that quotes or names a specific section, claim, or omission. Never bundle two questions.

- - **VERIFY:** the answer or the plan text it defends is checkable with local evidence. Load `references/claim-verification.md`, gather evidence, quote the authoritative doc, return VERIFIED / NOT VERIFIED / INCONCLUSIVE, then continue informed. Prefer VERIFY over asking when evidence can settle it.

- - **PUSH DEEPER:** the answer hand-waves complexity. Ask a sharper follow-up. Max 2 pushes per question.

- - **ACCEPT AND RECORD:** the answer closes the gap. Write the resolution into the plan file immediately, then re-score the dimension.

- - **REFRAME:** the concern does not apply as framed. Acknowledge what the user got right, then redirect to the actual gap.

-

- Stay on the same dimension until it reaches 5/5 or stalls, then move to the next-lowest below 5.

- **Stall rule:** after 2 pushes without a 5/5 answer, propose a concrete fix to accept or reject. If accepted, write it in and re-score. If the user defers, record what blocks 5/5 and move on. Don't keep re-asking in different words.

- After each dimension closes or stalls, re-render the triage table so the climb is visible. Sweep again over any dimension below 5. The loop ends when all six are 5/5, the user invokes the escape hatch, or a full sweep makes no progress (summarize what blocks 5/5 and stop).

- Lead with the final triage table (before and after). List residual gaps in three tiers; if every dimension reached 5/5, say so and leave "Must address" empty.

- - [SCOPE] `## Data Migration`: no incremental path; what if migration fails halfway?

- Resolved: NO

- - [ASSUMPTION] Plan assumes API rate limits won't be hit at projected scale

- Resolved: YES (user confirmed 80/min is within the 100/min limit with headroom)

- - [RISK] Single dependency on third-party service with no fallback

- Resolved: NO

- Plan edits happen incrementally during the loop; this final pass confirms the file is the deliverable: every resolution inline where its gap was identified; every stalled dimension carries a `<!-- UNRESOLVED: what blocks 5/5 -->` comment; a Review Notes section appended with before/after triage scores and the date. Do not ask permission to edit; updating the plan is the point. If the plan arrived as pasted text with no file, output the full updated plan in a code block and offer to write it to the active agent's native plan directory or a user-specified path.

- - No "great plan, but...": start with the triage table and go straight to gaps. Acknowledge strengths in one clause at most.

- - Direct but constructive; aim to strengthen, not criticize.

- - A question the code or docs can answer spends one of the 5-10 budget and returns what Step 1 would have read for free.

- - Past 10 questions the scope is too big for one plan. Asking an eleventh buys detail on a plan that cannot be executed in one pass; propose a split.

- - Blocking edges declared only in a ticket's prose are invisible to whatever picks the tickets up. Use the tracker's native blocking relation, and only where the dependency is real: a false edge parks a ticket that could have started.

- - Re-asking a stalled question in different words never produces the 5/5 answer. Propose a concrete fix to accept or reject, or record what blocks 5/5 and move to the next dimension.

- - A handoff plan with no named implementation-notes file loses every deviation the code forced on the executor, so review afterwards has nothing to read.

- - A handoff plan that says what trips a STOP but never what an acceptable finish looks like leaves an executor that trips nothing patching indefinitely, with nothing in the notes file recording how the run ended.

- - A plan that arrived as pasted text has no file to write resolutions into, so the whole Review evaporates when the session ends. Output the full updated plan in a code block and offer a path.

- Pipeline: `planning` -> implementation -> `pr-reviewer` -> `pr-creator` -> `pr-babysitter`.

-

- - `pr-reviewer`: code review after implementation; route here the moment the input is code, not a plan.

- - `codebase-architecture`: architectural decisions that feed into plans.