From c6e0483404f4fcb3f762fbe78a3bb6a5303c1d1a Mon Sep 17 00:00:00 2001 From: Clay Good Date: Wed, 15 Jul 2026 10:19:06 -0500 Subject: [PATCH] fix(schemas): resolve blocking open questions instead of deferring them 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: https://github.com/Fission-AI/OpenSpec/discussions/1296 Co-Authored-By: Claude Fable 5 --- schemas/spec-driven/schema.yaml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) 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.