write-design-doc

Draft a software design document by automating the creation of structured sections for Status, Context, Goals, Non-Goals, Proposed Design, Alternatives, Risks, and Rollout Plans to ensure alignment before implementation.

An architecture decision record for cross-team projects should include sections for Context, Goals and Non-Goals, Proposed Design, Alternatives Considered, Risks and Mitigations, Rollout Plan, Open Questions, and a Design Doc Attestation.

You need to write a design doc before coding when implementing non-trivial changes that touch multiple components or teams, requiring you to capture specific goals, constraints, risks, and rollout plans for clarity.

Capture architecture risks and mitigation strategies in a planning document using dedicated Risks and Mitigations sections, ensuring potential issues are documented alongside the proposed design and rollout plan.

The best way to structure an RFC for a system design rollout is to use a reproducible blueprint that separates Goals, Proposed Design, Alternatives Considered, and a detailed Rollout Plan to guide implementation and review.