spec driven development - markdown template

_template.md

<Title>:

• Branch:
• Status: Draft | In Progress | Ready for Review | Merged
• Owner(s): <name(s)>
• Created:
• Last Updated:
• Links: Issue · PR · Design/Doc

Purpose

• Problem statement and goals
• Non-goals / out of scope
• Success criteria / metrics

Approach

• High-level design and rationale
• Key decisions (runtime, libraries, patterns)
• Data flow / sequence (optional)
• Alternatives considered (brief)

Changes

• Routes / API contracts:
  • — <request/response changes>
• Database:
  • Migrations: <file(s)>, up/down strategy, backfill
• App code:
  • Components:
  • Lib/Agent:
• Config/Env/Flags: <new/changed vars and defaults>

Key Diffs vs main

• Commits: , (or link compare view)

Testing & Evals

• Unit/Integration: <what’s covered>
• E2E/Manual:
• Evals/Metrics:

Rollout & Backout

• Rollout plan / feature flag
• Migration/backfill steps
• Monitoring/alerts
• Backout plan

Risks & Open Questions

• — mitigation

Checklist

• Spec created and linked in PR
• DB migrations documented and reversible
• API changes documented and typed
• Tests/evals updated
• Observability and flags planned

Appendix (optional)

• Diagrams, screenshots, links to dashboards, or extended notes