#740 Recommend refine-plan only when decisions remain unsettled

[williamthorsen]

What

Fixes an issue where agents frequently recommended a refine-plan pass on plans whose decisions had already been settled during design. Agents are now instructed to recommend the pass only when a decision the plan depends on is still unsettled, and to name that decision in the recommendation itself.

Why

The rule that selects the recommended next step after planning could not return false for any substantive plan, so it functioned as a constant rather than a heuristic and the "implement directly with follow-up review" option was rarely reachable. The knowledge base records seven misfires across four repositories in the last month; in five, the user challenged the recommendation and the agent withdrew it on inspection. An earlier attempt narrowed the rule's trigger list, and every one of those seven episodes postdates it — the trigger list was never the problem. Sufficiency was.

Details

🐛 Bug fixes

• Rule 1 of the shared next-steps spec becomes an evidence test: it matches only when the agent can name a load-bearing decision the plan left unsettled. A decision is unsettled when the plan invented it and nothing has challenged it; it is settled when it was ratified interactively, carried in from prior design work, verified against source, or copied from an established pattern already in the codebase.
• The rule also fails when a plan's residual unknowns are empirical — answered by running code or writing the test. A refine pass re-reads the plan and structurally cannot resolve those, so they route to the next option instead.
• The condition "the plan has not been previously refined" is dropped. It is true by construction at plan time, since refinement runs after planning, and so carried no information. Its useful residue survives as evidence: a prior refine round that significantly altered the plan.
• The structural triggers (dependency-boundary changes, contract-shape changes, new interfaces, control-flow changes) are retained but demoted from a sufficient condition to evidence to weigh. Treating them as sufficient is what made the rule fire on everything.
• Selecting the refine option now requires naming the unsettled decision on a ➕ line in the rendered output. This is what makes the test binding rather than advisory: an agent with nothing to name cannot write the line, so the cascade falls through on its own.

♻️ Refactoring

• The rule's verdict is stated once at decision time and once at render time, rather than three times.
• The hint that maps a skill's recommendation context onto the settled/unsettled test moves into the rule itself, where it is read at the moment it is applied, rather than sitting under an unrelated heading two subsections away.

🧪 Tests

• spec-inlining.test.ts pins the five clauses the rule rests on across all four consuming skills: the naming test, the definition of "unsettled", the empirical discriminator, the demotion of the structural triggers, and the ➕ obligation. Each one, removed, restores a distinct failure.

Verification

The revised rule was walked against the seven recorded episodes that motivated the ticket. Each falls through to rule 2, and each fails on a clause the new text names explicitly:

Episode	Plan shape	Clause that fails rule 1
01KTW96Z	Return-type widening + new exported interface	settled — ratified interactively
01KW657D	Additive field on an established pattern	settled — verified against source
01KXBGZF	New tar reader	empirical residue (PAX long paths)
01KXBHF8	Data-structure semantics change	settled — consumer set enumerated against source
01KXE2X0	One test-only mock helper	empirical residue — answered by writing the test
01KXEJ4W	New shipped bin	settled — copied from an established pattern
01KXGFX3	New module + event envelope	settled — carried in from prior design (#984/#985)

The counter-check holds too: the rule remains reachable. A plan that invents a design decision no design phase challenged — where the decision is analytical and nameable — still matches. The option is down-weighted, not suppressed.

Closes #740

[github-actions]

Dependency audit

Production dependency audit passed.