Clarify proposal/design boundaries to reduce duplicated planning artifacts

[alessio-locatelli]

Problem

In the default spec-driven schema, proposal.md and design.md can substantially repeat one another. The proposal guidance correctly emphasizes motivation, while the design guidance asks for context, goals, and decision rationale; however, it does not explicitly tell authors to reference the proposal rather than restating its motivation, scope, or non-goals.

This can produce two documents containing the same problem statement and rationale, while the design omits its differentiated value: technical choices, alternatives, consequences, and trade-offs.

Suggested direction

Strengthen the default schema instructions (and, if useful, templates/examples) so the two artifacts have clearly complementary responsibilities:

• proposal.md: why the change is needed, the intended capability/outcome, affected contracts, and impact. Keep implementation-specific details out of What Changes.
• design.md: the technical approach needed to implement the approved proposal. Refer to the proposal for motivation and scope instead of repeating it; include only the current-state context and constraints needed to explain the approach.
• Require every material design decision to state the chosen option, meaningful alternatives considered, and the relevant consequences/trade-offs.

A short cross-reference example (for example, “See proposal.md § Why for motivation”) could make the intended relationship especially clear.

Acceptance criteria

• Generated instructions make the boundary between the two documents explicit.
• The design instructions explicitly discourage restating content already covered by the proposal.
• Decision guidance makes alternatives and trade-offs a first-class requirement.
• The change remains schema-level guidance, so projects can still customize their workflow.