An ADR captures one architecture decision: the context, the choice, the alternatives, and the consequences. prdwise treats ADRs as opt-in — you turn them on per project, and you can backfill them retroactively for existing work.

What it is

A short markdown file per decision, stored in your project. The create-adr workflow walks the agent through drafting one. The retroactive variant lets you write ADRs after the fact for decisions that are already in the code.

When to use it

• A decision will be expensive to reverse and you want the rationale on record.
• A decision is non-obvious and a future reader (or future you) will ask “why this and not the alternative?”
• You inherited a codebase and want to document the load-bearing choices retroactively.

When to skip it

• The decision is reversible and cheap to redo.
• The choice is obvious from the code and conventions.
• You are still exploring — write the ADR when the decision settles, not before.

How to enable

Follow docs/enable-adrs.md to add ADR support to your project. Once enabled, use the create-adr workflow whenever a decision warrants one. Retroactive ADRs use the same workflow with the framing flipped: you describe the decision already made and reconstruct the context.

Reference

• Workflow: create-adr.md
• Setup: docs/enable-adrs.md