Madhura68 8a7d419972 docs(adr): add ADR scaffolding (templates, README, meta-ADR)

Set up docs/adr/ as the canonical home for architecture decisions:

- templates/nygard.md — default four-section format (Status, Context,
  Decision, Consequences) for one-way-door decisions.
- templates/madr.md — MADR v4 with YAML front-matter and explicit
  Considered Options for decisions where rejected alternatives matter.
- README.md — naming convention (NNNN-kebab-case), template-selection
  guidance (Nygard default; MADR for auth, queue mechanics, agent
  integration), status lifecycle, and ADR roster.
- 0000-record-architecture-decisions.md — meta-ADR establishing the
  practice itself, in Nygard format.

Backfilling existing implicit decisions (base-ui-over-radix, float
sort_order, demo-user three-layer policy, etc.) is fase 6 of the
docs-restructure plan.

2026-05-02 21:25:26 +00:00

2.5 KiB

Raw Permalink Blame History

status

date

decision-makers

consulted

informed

proposed \| rejected \| accepted \| deprecated \| superseded by ADR-NNNN

YYYY-MM-DD when the decision was last updated

list everyone who participated in the decision

list everyone whose opinions were sought (typically subject-matter experts)	and with whom there was a two-way communication

list everyone who is kept up-to-date on progress	and with whom there is one-way communication

ADR-{{NNNN}}: {{short title, representative of solved problem and found solution}}

Context and Problem Statement

{{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}}

Decision Drivers

{{decision driver 1, e.g., a force, facing concern, …}}
{{decision driver 2, e.g., a force, facing concern, …}}

Considered Options

{{title of option 1}}
{{title of option 2}}
{{title of option 3}}

Decision Outcome

Chosen option: "{{title of option 1}}", because {{justification — e.g., only option which meets a knock-out criterion / which resolves a force / … turned out best (see "Pros and Cons of the Options" below)}}.

Consequences

Good, because {{positive consequence, e.g., improvement of one or more desired qualities, …}}
Bad, because {{negative consequence, e.g., compromising one or more desired qualities, …}}

Confirmation

{{Describe how the implementation of/compliance with the ADR can be confirmed. E.g., a test, a peer review, a runtime check.}}

Pros and Cons of the Options

Good, because {{argument a}}
Good, because {{argument b}}
Neutral, because {{argument c}}
Bad, because {{argument d}}

Good, because {{argument a}}
Bad, because {{argument b}}

Good, because {{argument a}}
Bad, because {{argument b}}

More Information

{{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when this decision the decision should be realized and if/when it should be re-visited. Links to other decisions and resources might appear here as well.}}

2.5 KiB Raw Permalink Blame History