fix(schemas): stop design.md from restating the proposal

[clay-good]

Status: Ready for review. Guidance-only change to the default spec-driven schema - no code paths, no CLI behavior, no schema structure changes.

What was wrong: #1382 - in the default schema, proposal.md and design.md often end up saying the same thing. The design instruction asked for "Background, current state, constraints, stakeholders" and "What this design achieves and excludes" without ever saying that motivation and scope already live in the proposal, so agents dutifully restated the proposal's Why and What Changes instead of adding the design's differentiated value (approach, alternatives, trade-offs). The proposal side already had its boundary line ("implementation details belong in design.md"); the design side had no equivalent.

How it was fixed: Two files, wording only:

• schemas/spec-driven/schema.yaml (design instruction): Context is scoped to "only the current state and constraints needed to explain the approach," with a cross-reference example ("See proposal.md - Why"); Goals / Non-Goals now says not to restate the proposal's scope; the closing guidance states the boundary explicitly - the proposal covers why and what, design covers how; reference rather than restate.
• schemas/spec-driven/templates/design.md: section comments mirror the same boundary, and the Decisions comment now mentions alternatives considered.

The third acceptance criterion in #1382 (alternatives and trade-offs as first-class decision content) was already met by the existing instruction ("Include alternatives considered for each decision") - this PR only surfaces it in the template comment.

Proof it works: schemas/ ships verbatim in the npm package and is parsed at runtime, so there are no compiled copies or golden hashes to regenerate (same shape as #1326 and #1366). Verified:

• schema.yaml still parses (artifacts: proposal,specs,design,tasks)
• Full suite after npm run build: 2,027 passed; the only 17 failures are the pre-existing environment-only zsh-installer ones tracked in ZshInstaller tests fail on machines with a real Oh My Zsh install (17/50 failures) #1321 / PR test(completion): isolate ZshInstaller tests from a real Oh My Zsh install #1400, identical on main
• skill-templates-parity, artifact-graph/resolver, and instruction-loader tests all green

Notes: Deliberately does not touch the proposal instruction (its boundary line already exists, and #1399 currently has open edits in that section). Design/architecture untouched - this clarifies the schema's existing intent (the instruction already said "Reference the proposal for motivation").

Closes #1382

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated design document guidance with clearer “Context” framing, explicit scope boundaries, and clearer responsibilities between proposal (“why/what”) and design (“how”).
  • Revised the design markdown template to better reference proposal details and prompt for alternatives considered.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d9c9ce5b-ade7-4c9e-8206-6d4ad5ef95c6

📥 Commits

Reviewing files that changed from the base of the PR and between 15bd1b4 and ddc8de8.

📒 Files selected for processing (1)

• schemas/spec-driven/schema.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• schemas/spec-driven/schema.yaml

---

📝 Walkthrough

Walkthrough

The spec-driven schema now distinguishes proposal responsibilities from design responsibilities, limits duplicated context, and clarifies design decision guidance. The design template comments reference proposal.md and include alternatives considered.

Changes

Proposal and design guidance

Layer / File(s)	Summary
Schema guidance schemas/spec-driven/schema.yaml	Refines Context and Goals / Non-Goals guidance, defines proposal as “why/what” and design as “how”, and directs authors to reference existing proposal and specification content.
Design template alignment schemas/spec-driven/templates/design.md	Updates section comments to reference proposal.md for current state and constraints and to include alternatives considered in design decisions.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• Fission-AI/OpenSpec#1326: Refines spec/design scope boundaries in the spec-driven schema.
• Fission-AI/OpenSpec#1366: Updates schema instructions for generating design.md.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: tightening design.md so it does not repeat the proposal.
Linked Issues check	✅ Passed	The updates make proposal/design boundaries explicit and reinforce alternatives and trade-offs as required by #1382.
Out of Scope Changes check	✅ Passed	The PR stays within schema-level wording and template guidance, with no unrelated code or behavior changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/design-proposal-boundary

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with 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.

Inline comments:
In `@schemas/spec-driven/schema.yaml`:
- Around line 129-131: Align the guidance with the design dependency by updating
the design requirements near the proposal/specs instructions to include specs in
design.requires, ensuring specs exist before design generation. Preserve the
existing proposal dependency and avoid changing unrelated documentation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 9d5c7bf3-79f7-4813-9856-42deefe78c8e

📥 Commits

Reviewing files that changed from the base of the PR and between 60f720c and 15bd1b4.

📒 Files selected for processing (2)

• schemas/spec-driven/schema.yaml
• schemas/spec-driven/templates/design.md

[alfred-openspec]

The proposal/design boundary is now explicit without changing the existing parallel artifact ordering, and the template mirrors the schema guidance. Exact-head build plus 96 focused schema, resolver, and instruction-loader tests passed.