fix(schemas): resolve blocking open questions instead of deferring them to design.md#1366
Conversation
…em to design.md The design instruction told agents to end design.md with an Open Questions section but never said what to do with those questions, so blocking decisions flowed silently into tasks and implementation. Now the design instruction scopes the section to safely deferrable unknowns and tells the agent to ask the user about anything that would change the specs, approach, or tasks; the tasks instruction adds the matching check before writing the task list. Discussion: #1296 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughChangesSpec-driven workflow guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@schemas/spec-driven/schema.yaml`:
- Around line 125-128: Update the task-phase instruction in the schema to use
the same blocking criteria as the design-phase check: unresolved questions
affecting the specifications, chosen approach, or task breakdown must be
resolved with the user before writing tasks. Keep the existing requirement to
inspect design.md and avoid unstated assumptions in tasks.md.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 87819c38-8ab9-4677-b658-fccdbefc1727
📒 Files selected for processing (1)
schemas/spec-driven/schema.yaml
| Before writing tasks, check design.md for Open Questions. If any of them | ||
| would change what gets built, resolve them with the user first - do not | ||
| bake an unstated assumption into the task list. | ||
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Keep the task-phase check aligned with the design-phase criteria.
The design instruction also treats changes to the specifications, chosen approach, or task breakdown as blocking. Reuse those same three criteria here so an unresolved approach or planning decision cannot be baked into tasks.md.
Proposed fix
Before writing tasks, check design.md for Open Questions. If any of them
- would change what gets built, resolve them with the user first - do not
+ would change the specs, the chosen approach, or the task breakdown,
+ resolve them with the user first - do not
bake an unstated assumption into the task list.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Before writing tasks, check design.md for Open Questions. If any of them | |
| would change what gets built, resolve them with the user first - do not | |
| bake an unstated assumption into the task list. | |
| Before writing tasks, check design.md for Open Questions. If any of them | |
| would change the specs, the chosen approach, or the task breakdown, | |
| resolve them with the user first - do not | |
| bake an unstated assumption into the task list. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@schemas/spec-driven/schema.yaml` around lines 125 - 128, Update the
task-phase instruction in the schema to use the same blocking criteria as the
design-phase check: unresolved questions affecting the specifications, chosen
approach, or task breakdown must be resolved with the user before writing tasks.
Keep the existing requirement to inspect design.md and avoid unstated
assumptions in tasks.md.
alfred-openspec
left a comment
alfred-openspec
left a comment
There was a problem hiding this comment.
The design and tasks instructions enforce the decision boundary at both artifact-generation points while preserving genuinely deferrable questions. The focused behavior and full CI look good.
2 participants
Status: Ready for review. One file, +10/-1, instruction text only.
What was wrong: The design instruction told agents to end
design.mdwith an "Open Questions" section but never said what to do with those questions. Agents dutifully wrote down unresolved decisions and moved straight on to tasks, silently picking answers along the way. Users hit this and don't know whether they're supposed to answer the questions before continuing — that's exactly the confusion in discussion #1296 ("should we address this Open Questions before we proceed... or opsx:continue will handle this?").How it was fixed: Two instruction edits in
schemas/spec-driven/schema.yaml(read at runtime, no build step):design.mdfor Open Questions and resolve blocking ones with the user, so the check still fires when tasks are generated in a later session (/opsx:continue).Proof: YAML parses, and the real CLI emits the new text:
vitest run test/commands/schema.test.ts test/core/artifact-graph/resolver.test.ts test/commands/artifact-workflow.test.ts test/core/view.test.ts— 123 tests passed.Notes: Touches a different hunk of the same file as #1326 (specs instruction), so the two won't conflict. No changeset, matching #1326.
Closes the question raised in discussion #1296.
🤖 Generated with Claude Code
Summary by CodeRabbit