Apply recommendation gradient to all substantive option choices

[williamthorsen]

Problem

The recommendation-gradient spec exempts two surface forms ("next-steps menus" and confirmation prompts, rendered with 👍🏼👎🏼) from the marker + pros/cons format. Both carve-outs are too broadly worded: Agents apply them whenever the surface framing matches, even when the underlying choice carries substantive tradeoffs the gradient is meant to surface. Real design choices get presented as templated workflow choices or one-bit approvals, losing the strength signals and rationale the gradient would have conveyed.

A first-pass migration of the next-steps templates to the gradient form regressed a prior framing fix (PR #557 / issue #544): the gradient's mandatory ➕/➖ rows reintroduced a description for option 3 ("Implement directly"), and the chosen con line ("no independent review pass") revived the same leak that #557 had specifically removed. Closing the regression requires restructuring the templates to surface "Implement directly with follow-up review" and "Implement directly" as two distinct options, mirroring the trivial-vs-non-trivial distinction already present in complexity-classification.md's consumer-levels table.

Context

Observed twice in the spec, plus a regression observed mid-implementation:

1. Next-steps misclassification (originally raised in Apply recommendation gradient to all substantive option choices #592 on 2026-05-16): An agent presented three follow-up options for a design decision (make a change / measure first / leave it), each carrying meaningful tradeoffs (size impact, reversibility, information value). The agent omitted the gradient because the heading "What I'd do next" matched the carve-out at packages/agents/content/skills/_data/recommendation-gradient.md line 9.

2. Confirmation-prompt overreach: The 👍🏼👎🏼 convention covers any binary, but substantive yes/no choices (e.g., "Want me to also extract a helper?", "Should we run the migration now or wait?") have both a recommendation strength and consequences worth listing. The current spec doesn't distinguish procedural confirmations (where "no" means "let's talk more") from substantive binaries (where "no" designates a concrete alternative agent action).

3. Option-3 framing-leak regression (surfaced 2026-05-18 during review): Migrating the existing three-option next-steps-after-plan.md and next-steps-after-review.md templates to the gradient form reintroduces a description for option 3 ("Implement directly"). PR #544 Stop under-recommending direct implementation #557 had previously emptied that description cell precisely because any content in it tended to define option 3 by what it lacked. The natural fix is to split option 3 into a review-paired path ("Implement directly with follow-up review") and a no-review path ("Implement directly"), each with its own positive framing.

Two contributing factors to the carve-out problem:

• The spec's existing positive example ("Want me to: 1. ■□□ Use a single config file …") is structurally identical to the misclassified menu. Its presence isn't enough, because agents key on the carve-out's literal wording when it matches the heading they're producing.
• The 🟢 recommended convention and the gradient overlap functionally (both identify the lead option). Maintaining two conventions for the same purpose is what creates the boundary agents have to classify against.

The carve-out wording, 🟢 recommended convention, and trivial-vs-non-trivial distinction appear in:

• packages/agents/content/skills/_data/recommendation-gradient.md
• packages/agents/content/guidance/shared/AGENTS.md
• packages/agents/content/skills/_data/next-steps-after-plan.md
• packages/agents/content/skills/_data/next-steps-after-review.md
• packages/agents/content/skills/_data/complexity-classification.md

packages/agents/content/skills/assess-ticket/next-steps-after-assessment.md lists options without recommending any (the gradient's existing "pure taste call" form) and doesn't need migration.

Proposed solution

Make the gradient the framework that governs all option-style lists with substantive tradeoffs, tighten the confirmation-prompt boundary, and migrate the next-steps templates without regressing the option-3 framing fix:

1. Drop the next-steps-menu carve-out. The gradient applies to next-steps menus. Templates that recommend an option do so by setting marker strength; templates that don't recommend use the gradient's pure-taste-call form.
2. Tighten the confirmation-prompt definition. A confirmation prompt is only for cases where "no" means redirect or discuss further. Substantive binary choices (where "no" designates a concrete alternative agent action) use the gradient with two numbered options.
3. Restructure the two next-steps templates with deterministic recommendation rules (next-steps-after-plan.md, next-steps-after-review.md) to four options each: a heaviest rework path (Refine plan or Design and plan), Orchestrate, "Implement directly with follow-up review", and "Implement directly". Each option carries a gradient marker and brief pros/cons; the recommendation rules pick a single recommended option that earns the strongest marker, with the other three carrying weaker markers by default.
4. Mirror the trivial-vs-non-trivial distinction in complexity-classification.md: the next-steps-after-review consumer-levels row gets the same two-case treatment as the next-steps-after-plan row, so both consumers default to "Implement directly with follow-up review" and downgrade to "Implement directly" only for trivial work.
5. Retire the 🟢 recommended convention. The gradient marker is sufficient signal for the lead option.
6. Add a contrast example to the gradient spec showing the same surface phrasing ("Want me to …?") handled both ways: as 👍🏼👎🏼 when procedural, as a 2-option gradient list when substantive.
7. Mirror the tightening in packages/agents/content/guidance/shared/AGENTS.md so the rule reads consistently in both locations.
8. Bring all new pros/cons indent prefixes (contrast example, four-option example blocks in both templates) into byte-level alignment with the spec's existing canonical example: three non-breaking-space characters per the rule the spec already states.

Acceptance criteria

• recommendation-gradient.md no longer carves out next-steps menus. The gradient applies to all option-style lists with substantive tradeoffs.
• recommendation-gradient.md defines confirmation prompts positively (the user's response is approve-or-redirect; "no" does not designate a concrete alternative action) and states explicitly that yes/no choices with substantive tradeoffs use the gradient with two numbered options.
• recommendation-gradient.md contains a contrast example pair: a procedural binary handled with 👍🏼👎🏼 and a substantive binary handled with the gradient.
• All pros/cons indent prefixes in the spec's examples (canonical, taste-call, multi-question, contrast) use three non-breaking-space characters per the spec's existing universal rule.
• next-steps-after-plan.md and next-steps-after-review.md's findings sub-block each present four options: a rework path, Orchestrate, "Implement directly with follow-up review", and "Implement directly". Each option carries a gradient marker and brief pros/cons.
• The four-option recommendation rules in each template pick a single recommended option for any given context; that option carries the strongest marker, with the other three carrying weaker markers per the gradient's defaults.
• complexity-classification.md's next-steps-after-review consumer-levels row mirrors the next-steps-after-plan row's distinction between "Implement directly with follow-up review" (default) and "Implement directly" (trivial only).
• No remaining references to 🟢 recommended in the agents content tree.
• The corresponding prompt-formatting bullet in packages/agents/content/guidance/shared/AGENTS.md matches the tightened spec.
• Skill-local references to the next-steps formatting convention are updated to reflect the gradient-based form.