plan-change

plan-change

Two outputs, in order: a clarity rating, then (only if clear enough) a technical plan.

Step 1 — Clarity rating (gate, do not skip)

You already hold the full codebase context (via recall-memory). Read every .claude/specs/specN.md in scope. Rate how confidently the spec can be implemented in the right place, without guessing, 0–10:

• 9–10 — unambiguous what and where; you can name the exact files/symbols to change and predict the blast radius.
• 6–8 — intent clear but location/edge-cases uncertain; implementing now risks touching the wrong place.
• ≤5 — underspecified; high chance of "small mistake, whole-codebase damage."

If clarity < threshold (default 9, from .claude/builder/settings.json): do not plan. Return the specific blocking questions and why each matters in code terms (e.g. "spec says 'update the auth check' — RBAC lives in custom middleware at Startup.cs:228 AND per-controller attributes; which layer?"). The orchestrator surfaces these to the user; nothing is written until answered.

Step 2 — Technical plan (only if clarity ≥ threshold)

Write to .claude/builder/PLAN.md. Required sections (the deterministic gate validate-plan.sh checks these — missing any sends the plan back). When micro_decomposition is on (the default, read from .claude/builder/settings.json), the ## Tasks breakdown is also required and gated — follow the micro-decompose skill (${CLAUDE_PLUGIN_ROOT}/skills/micro-decompose/SKILL.md) for right-sizing and the edge-case taxonomy:

# builder plan — <spec id / short title>

Clarity: N/10

## Goal
What the spec asks for, in one or two sentences. No scope beyond the spec — not 1% extra.

## Scope (files this change may touch)
- path/to/file.ext        <- exact repo-relative paths, one per bullet, path first
- path/to/other.ext
(The PreToolUse guard blocks edits to anything not listed here.)

## Approach
Ordered steps. Each step cites evidence as path:line for anything it relies on
(e.g. "extend the handler at OrderService.cs:142"). Separate EVIDENCE (seen in
code) from INFERENCE (assumed) explicitly.

## Tasks
(Required when `micro_decomposition` is on — the default. Skip this section only
when it is off.) Decompose the change per the `micro-decompose` skill into the
smallest INDEPENDENTLY-VERIFIABLE units — proportional, never over-split: a
one-line change is ONE task. One block per task, FIXED schema (the deterministic
gate `validate-plan.sh` parses it):

### Task 1 — <short intent>
- Files/functions: <exact repo-relative paths / symbols this unit touches>
- Existing pattern: <the established pattern/file this follows + the callers of any symbol it changes — see "Explore before change" below>
- Behavior: <precise input → output; the ONE thing this unit does>
- Edge cases:
  - <case> → <intended handling>     (≥1; pull in the relevant MEMORY.md risks by name)
- Definition of Done: <observable, testable completion incl. edge coverage — not just "compiles">

### Task 2 — <…>
- …

## Risks & invariants (from MEMORY.md)
- Invariants this change must preserve (cite the MEMORY.md risk map).
- New risks this change introduces and how the plan mitigates them.

## Test strategy
How the change will be verified (feature-level cases incl. edge cases; what
app-level regression matters). Names the existing harness if one exists.

## Assumptions & open questions
Anything still uncertain. If this list is non-trivial, clarity was over-rated —
drop the score and return to Step 1.

Explore before change (prevents duplicates & convention breaks)

Before you write a task, find what already exists — recall from MEMORY.md/index.json first, then narrow with grep/ripgrep on concrete symbols:

• Locate the existing pattern for what you're about to add (how similar things are done here). Plan to follow it, not invent a parallel one. Record it in the task's Existing pattern: line.
• For any symbol a task will change, find ALL its callers/usages and list the ones that could break under Existing pattern: (or in Risks). A change that ignores its callers is how "small mistake, whole-codebase damage" happens. This is cheap search — it can run at the low-effort tier (see the context-finder / recall-memory retrieval doctrine). Return summaries, not raw file dumps.

Honesty rules

• Never claim certainty you can't cite. "100% understood" is not allowed; state coverage and assumptions.
• Implement only what the spec says. If you notice an unrelated improvement, list it under Assumptions as a suggestion for the user, never silently add it.
• Proportionality: the ## Tasks count tracks distinct behaviors, not lines of code. A trivial spec stays 1–2 tasks. If the breakdown wants many tasks for a small spec, collapse it; if a spec truly needs many, flag in Assumptions that it may be several specs.

Return to orchestrator (keep it short, ≤10 lines)

Clarity score; if clear: the Scope file list + the single riskiest step + your self-rating of the plan vs. spec/standards. The orchestrator re-rates and runs validate-plan.sh before any implementation.