subagent-driven-development: add a mechanical-migration mode for verbatim-diff plans

[bradfeld]

Summary

Subagent-driven-development's per-task two-stage review (spec compliance, then code quality, as separate subagent dispatches) is excessive ceremony for verbatim-diff migration plans — refactor sweeps where each task is a mechanical Find/Replace patch and "the spec IS the diff." A mechanical-migration mode (or equivalent prompt-conditional collapse) that combines the two stages into a single combined-review dispatch — or skips spec-review entirely for verbatim-diff tasks — would meaningfully reduce dispatch volume and wall-clock time without losing the bug-catching value of the review pipeline.

Concrete experience driving the request

I just executed a 6-dialog migration sweep (8 tasks total) via SDD. The plan was a textbook verbatim-diff sweep: each consumer task included a literal "Find this 8-line block / Replace with this 9-line block" specification. Across the 8 tasks I ran:

• Task 1 (foundational platform component): full 2-stage review earned its keep — the code-quality reviewer flagged a data-slot selector stability finding that became material to subsequent tasks.
• Tasks 2–7 (mechanical consumer migrations): I ad-hoc-compressed to combined-review (one subagent doing both spec + quality per task) starting at Task 3. Zero false negatives across the 5 combined-reviewed tasks. The one real semantic deviation (Task 7's cancelDisabledWhilePending=false opt-out, where the original cancel button had no disabled attribute) was caught at implementation time via a verify-before-apply step in the dispatch prompt — not at review time. Spec-review's job, when "the spec IS the diff," collapses to git diff.
• The load-bearing bug-catch came from /commit's codex-reviewer at the cumulative-diff layer, not per-task. Codex spotted that the cancel button in DialogFooterActions was missing type="button" — inside a <form>, an untyped button defaults to type="submit", so clicking Cancel would submit the form. Both Sonnet-family per-task reviewers (spec + quality) had read the same diff 12 times across 6 tasks and missed it. This is the kind of finding that surfaces only at the cumulative-diff cross-cutting layer, not at the per-task level — exactly the layer where the per-task review investment pays its lowest dividend.

The 5 per-task spec-reviews returned 0 actionable findings. The implementer's verbatim-diff compliance was easily verifiable by orchestrator-side git diff after each commit. The dispatches were ceremony, not insight.

What I'd propose

Option A — explicit mechanical-migration mode trigger. When the plan body contains Find: / Replace with: blocks (or equivalent verbatim-diff markers) in N tasks, the SDD skill's per-task workflow becomes:

1. Implementer dispatch (unchanged)
2. One combined reviewer dispatch covering both spec compliance and code quality (collapse the current two stages into a single prompt)
3. (Or even: skip per-task review entirely and rely on the final cumulative review)

The trigger could be:

• Auto-detected from plan content (presence of literal Find: / Replace with: blocks across ≥ N% of tasks)
• Explicit annotation in the plan's frontmatter (mode: mechanical-migration)
• A user-passed flag at /sdd-execute time

Option B — relax the rigid two-stage rule. SKILL.md currently says: "Skip code quality review before spec compliance is ✅ (wrong order)" and "Move to next task while either review has open issues". For verbatim-diff tasks, soften this to "Combined-review acceptable when task spec is verbatim-diff". A note in the skill's "When to Use" decision tree could route mechanical migrations to a lighter path without forking the whole skill.

Option C — orchestrator-side hint. Document in SKILL.md that orchestrators MAY dispatch a single combined reviewer instead of two-stage when the per-task scope is "apply this verbatim diff" — and acknowledge the existing implementer-prompt's "verify the original file before applying" pattern as the front-line behavior-preservation guard.

I'm happy to send a PR for any of these if you'd like to discuss shape first. My current local approach (without modifying SDD) is to route similar future plans to executing-plans (inline) rather than SDD — which works, but loses SDD's fresh-context-per-task isolation benefit for the genuinely novel Task 1 portion of mixed plans.

Context

• Run details: 6-dialog migration sweep across 3 apps (intensitymagic, authormagic, curecancermagic) consolidating to a shared DialogFooterActions component. 1026 tests passing, behavior preserved across all 6 migrations, 1 critical bug caught at the cumulative-diff layer (the form-submit-on-cancel regression).
• Time profile: estimated ~50% reduction in subagent-dispatch volume achievable on similar plans without losing bug-catching, based on the 5 zero-finding spec reviews.
• I'm using the superpowers plugin via the Claude Code marketplace (currently 5.0.7).

Linked artifacts (if helpful)

• The implementation plan that exhibited the pattern: 2026-04-27-pla-1432-dialog-footer-actions-sweep.md (in my repo)
• The codex-reviewer-caught critical bug: missing type="button" on the cancel button inside DialogFooterActions