Doc Adr

Generate ADR

Path Resolution

1. Read workflow.json in the project root
2. If it exists and docsRepo is ".": this IS the docs repo — use local paths
3. If it exists and docsRepo is a repo name: resolve via pwsh .claude/skills/tool-worktree/scripts/resolve-repo.ps1 <docsRepo> to get the docs root path. Templates at <resolved>/templates/, output to <resolved>/adr/
4. If no workflow.json: templates at templates/, output to docs/adr/

Instructions

1. Resolve paths (see Path Resolution above)
2. Read the template at <templates>/adr.md
3. Determine the ADR number by checking existing files in the output directory and incrementing
4. Gather the decision context:
   • What was decided?
   • What options were considered?
   • Why was this option chosen?
   • Who was involved in the decision?
5. Generate the ADR using MADR format:
   • Context: Neutral description of the situation
   • Decision Drivers: What factors influenced the decision
   • Options: At least 2-3 genuine options with pros and cons
   • Decision Outcome: Clear statement of what was chosen and why
   • Consequences: Honest positive, negative, and neutral consequences
6. Save to <output>/[number]-[slug].md (e.g., <output>/0012-use-event-sourcing.md)

Quality Checklist

• Context is neutral (doesn't pre-argue for the chosen option)
• At least 3 decision drivers listed
• At least 2 real options (not strawmen)
• Each option has both pros and cons
• Decision outcome includes "because" with clear justification
• Consequences include at least one negative (every decision has trade-offs)
• Validation section says how we'll know if this was the right call

Tips

• ADRs are immutable — if a decision changes, supersede the old ADR with a new one
• Write the context as if explaining to someone who joins the team in 6 months
• Be honest about negative consequences — the point is to document the trade-off, not sell the decision
• Link to the RFC or design doc that led to this decision