Skip to content

fix(schemas): resolve blocking open questions instead of deferring them to design.md #1366

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
clay-good merged 1 commit into from
Jul 17, 2026
Merged

fix(schemas): resolve blocking open questions instead of deferring them to design.md #1366

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 10 additions & 1 deletion schemas/spec-driven/schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,12 @@ artifacts:
- **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
- **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
- **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
- **Open Questions**: Outstanding decisions or unknowns to resolve
- **Open Questions**: Unknowns that can safely be answered later without
changing the specs, the approach, or the task breakdown. Omit if none.

Open questions are for genuinely deferrable unknowns, not decisions you
skipped. If a question would change the specs, the chosen approach, or
the task breakdown, resolve it now - ask the user instead of guessing.

Focus on architecture and approach, not line-by-line implementation.
Reference the proposal for motivation and specs for requirements.
Expand All @@ -117,6 +122,10 @@ artifacts:
instruction: |
Create the task list that breaks down the implementation work.

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.

Comment on lines +125 to +128

@coderabbitai coderabbitai Bot Jul 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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.

Suggested change
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.

**IMPORTANT: Follow the template below exactly.** The apply phase parses
checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.

Expand Down
Loading