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). diff --git a/schemas/spec-driven/schema.yaml b/schemas/spec-driven/schema.yaml index b3f1611327..216422e2d3 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, 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: 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