Resolve: teach the prompt to treat design/spec comments as binding scope#628
Merged
Conversation
Bridge-analysis #436 surfaced the failure mode: vague issue body ("we are getting to the point that I would like to launch this as a web app...") + detailed spec in /agent-delegate comments → agent scope-reduces to a tractable subset (schema + CLI), opens PR #437 (3 files, 40 LOC), declares victory. 85% of the spec dropped on the floor. The fix is NOT delegate-specific. Manual /agent-design → /agent-resolve would hit the same shortcut: the resolve system prompt biases toward small fixes ("a simple fix should take 5-10 iterations; a complex multi-file change rarely needs more than 20-30", "modify existing files rather than creating new ones", "call finish() as soon as the task is done"). For a spec-driven implementation those are actively wrong. ## What changes 1. New SCOPE section in the prompt (wired into build_system_prompt between AGENT_ROLE and the budget paragraph). Says: "If the comments contain a substantial design analysis, implementation spec, or output from a prior /agent-design, /agent-workshop, or /agent-delegate run, treat the most recent revised version as the binding contract for your work — NOT the issue body alone." Plus an explicit anti-shortcut nudge: "Scope-reducing to 'the foundational piece' and shipping a tiny PR is the wrong outcome — it leaves the issue effectively unresolved..." 2. Iteration-budget paragraph acknowledges spec-driven scope: "Implementing a detailed multi-component spec (see ## Scope above): 50-100+ iterations — every file, route, table, and test the spec lists has to be created. Stopping at 20-30 to ship a 'foundational' subset is the wrong call when a spec is the contract." 3. WORKFLOW step 3 ("Implement") softens "modify existing files rather than creating new ones" to apply only to bug fixes — for spec-driven work, the spec defines the file set. ## Why one prompt, not a delegate-specific one Delegate is a macro: it expands into the same agentic calls a user could invoke manually. The user's stated preference: delegate should look like calling the steps in sequence. If we put the scope rule in a delegate-only Stage 4 prompt, the two paths drift and the manual flow keeps shortcutting. Putting it in resolve's general prompt means it triggers for both, no separate prompt to keep in sync. 8 new tests pin the SCOPE wording + budget-paragraph update + the fact that SCOPE is actually wired into build_system_prompt's output. 670 unit tests total pass (was 662).
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Bridge-analysis #436 surfaced the failure mode: vague issue body + detailed spec in `/agent-delegate` comments → agent scope-reduces to a tractable subset (schema + CLI), opens PR #437 (3 files, 40 LOC), declares victory. ~85% of the spec dropped on the floor.
Not a delegate-specific problem
Manual `/agent-design` → `/agent-resolve` would hit the same shortcut. The resolve system prompt biases toward small fixes:
For a spec-driven implementation those are wrong.
Fix — in resolve's general prompt (one source of truth)
Per the chat discussion: delegate is a macro that expands to the same agentic calls a user could invoke manually. The fix lives in resolve's prompt so it triggers identically for both flows; no delegate-specific Stage 4 prompt to drift.
Three changes:
New SCOPE section wired into build_system_prompt (between AGENT_ROLE and the budget paragraph). Says: if comments contain a substantial design analysis, implementation spec, or output from a prior `/agent-design` / `/agent-workshop` / `/agent-delegate` run, treat the most recent revised version as the binding contract — not the issue body alone. Plus explicit anti-shortcut framing.
Iteration-budget paragraph acknowledges spec-driven scope: "implementing a detailed multi-component spec: 50-100+ iterations — every file, route, table, and test the spec lists has to be created."
WORKFLOW step 3 softens "modify existing files rather than creating new ones" to apply only to bug fixes — for spec-driven work, the spec defines the file set.
Test plan
🤖 Generated with Claude Code