diff --git a/schemas/spec-driven/schema.yaml b/schemas/spec-driven/schema.yaml index 45f61e222b..f97ba7a0d5 100644 --- a/schemas/spec-driven/schema.yaml +++ b/schemas/spec-driven/schema.yaml @@ -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. @@ -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. + **IMPORTANT: Follow the template below exactly.** The apply phase parses checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.