From 15bd1b4c76180bcb442c260c34616815100b958c Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 20 Jul 2026 16:36:04 -0500 Subject: [PATCH 1/3] fix(schemas): keep design.md from restating the proposal The spec-driven design instruction asked for background, current state, and goals without saying the motivation and scope already live in proposal.md, so generated designs often duplicated the proposal instead of adding technical decisions. Scope the Context and Goals guidance to what the approach needs, and state the boundary explicitly: the proposal covers why and what, design covers how - reference, don't restate. Closes #1382 Co-Authored-By: Claude Fable 5 --- schemas/spec-driven/schema.yaml | 8 +++++--- schemas/spec-driven/templates/design.md | 4 ++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/schemas/spec-driven/schema.yaml b/schemas/spec-driven/schema.yaml index b3f1611327..98b3a60f8e 100644 --- a/schemas/spec-driven/schema.yaml +++ b/schemas/spec-driven/schema.yaml @@ -113,8 +113,8 @@ artifacts: - Ambiguity that benefits from technical decisions before coding Sections: - - **Context**: Background, current state, constraints, stakeholders - - **Goals / Non-Goals**: What this design achieves and explicitly excludes + - **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why"). + - **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries. - **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) @@ -126,7 +126,9 @@ artifacts: 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. + The proposal covers why and what; design covers how. Reference the + proposal for motivation and specs for requirements - if a section + would only restate them, point to them instead. Good design docs explain the "why" behind technical decisions. requires: diff --git a/schemas/spec-driven/templates/design.md b/schemas/spec-driven/templates/design.md index 4ab5bd8393..78fcc34345 100644 --- a/schemas/spec-driven/templates/design.md +++ b/schemas/spec-driven/templates/design.md @@ -1,6 +1,6 @@ ## Context - + ## Goals / Non-Goals @@ -12,7 +12,7 @@ ## Decisions - + ## Risks / Trade-offs From ddc8de85ec6825478d444aebc7e3a9b238b76883 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Mon, 20 Jul 2026 16:46:33 -0500 Subject: [PATCH 2/3] fix(schemas): qualify the specs reference for design's parallel ordering design.requires is [proposal] only, so a design can be drafted before the specs exist. Say "once written" instead of implying the specs are always there to reference. Co-Authored-By: Claude Fable 5 --- schemas/spec-driven/schema.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/schemas/spec-driven/schema.yaml b/schemas/spec-driven/schema.yaml index 98b3a60f8e..216422e2d3 100644 --- a/schemas/spec-driven/schema.yaml +++ b/schemas/spec-driven/schema.yaml @@ -127,8 +127,8 @@ artifacts: Focus on architecture and approach, not line-by-line implementation. The proposal covers why and what; design covers how. Reference the - proposal for motivation and specs for requirements - if a section - would only restate them, point to them instead. + proposal for motivation and, once written, the specs for requirements - + if a section would only restate them, point to them instead. Good design docs explain the "why" behind technical decisions. requires: From 7d396d8be351a33055e72226583ec6526567e272 Mon Sep 17 00:00:00 2001 From: Clay Good Date: Wed, 22 Jul 2026 08:09:47 -0500 Subject: [PATCH 3/3] chore(changeset): add the patch changeset for the design/proposal boundary schemas/ ships in the npm package files list, so this guidance change reaches users on upgrade and needs a changelog entry. The Validate Release Tracking check only validates changesets when present, so its absence was not caught. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/design-proposal-boundary.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/design-proposal-boundary.md diff --git a/.changeset/design-proposal-boundary.md b/.changeset/design-proposal-boundary.md new file mode 100644 index 0000000000..ba25d51e08 --- /dev/null +++ b/.changeset/design-proposal-boundary.md @@ -0,0 +1,5 @@ +--- +"@fission-ai/openspec": patch +--- + +Stop `design.md` from restating the proposal. In the default `spec-driven` schema, the design instruction asked for "Background, current state, constraints, stakeholders" and "What this design achieves and excludes" without saying that motivation and scope already live in `proposal.md`, so agents restated the proposal's Why and What Changes instead of adding the design's own value - approach, alternatives, and trade-offs. The instruction and the design template now state the boundary explicitly (the proposal covers why and what, design covers how) and tell the agent to reference those documents rather than repeat them (#1382).