devbooks-design-doc

A design doc ensures traceability by defining What, Constraints, and Acceptance Criteria, then explicitly citing affected requirements and invariants from existing source of truth specs. This structure links each change package directly to established glossary and spec definitions.

Structure the design doc by capturing only What, Constraints, and Acceptance Criteria, plus Documentation Impact and Architecture Impact sections. This verifiable format focuses on defining the change package boundaries rather than outlining the actual implementation steps.

Generating a design.md file creates a Golden Truth reference for downstream workflows like spec-contract, implementation-plan, test-owner, and coder. It provides the approved What, Constraints, and Acceptance Criteria needed to generate accurate downstream contracts and plans.

Yes, existing truth specs and invariants are required. The design doc references these established sources of truth to maintain alignment, ensuring the new change package respects current architecture and requirements definitions before proposal planning proceeds.

A design doc approach actually helps establish formal acceptance criteria by enforcing a structure that requires them. By generating the document with What, Constraints, and ACs, you define verifiable conditions even if your project previously lacked them.

Architecture Impact and Documentation Impact sections are needed to assess how a change package alters the current system structure and existing truth specs. They ensure the design doc captures verifiable constraints and maintains alignment with the broader technical architecture.