/docs/adr/* + .agents/skills/record-architecture-decisions/SKILL.md

README.md

Architecture Decision Records

This directory preserves why durable technical decisions made sense given the constraints and evidence available at the time.

Create an ADR when a change chooses among meaningful alternatives, moves from an ideal approach to a practical one because of discovered constraints, establishes a cross-component convention or contract, accepts a consequential trade-off, or replaces an earlier decision. Do not create one for routine maintenance or implementation details.

Name records YYYY-MM-DD-short-title.md and start from template.md. Keep them small and land them with the change they explain.

A merged ADR is accepted. Do not add status or approver fields. When a decision changes, add a new ADR with a Supersedes link instead of rewriting history.

AGENTS.md

Architecture Decision Records

Repository history and durable technical decisions are recorded in docs/adr/.

Before completing any non-trivial implementation thread or merge request, use the repository's record-architecture-decisions skill to evaluate whether the work produced a durable architectural decision.

When a decision is ADR-worthy, add a small record under docs/adr/ in the same merge request. Capture the constraints and evidence available at the time, including failed or rejected approaches that explain why the practical solution differed from the ideal one. If no ADR is needed, say so explicitly in the final handoff.

SKILL.md

name

record-architecture-decisions

description

Record small Architecture Decision Records (ADRs) for durable technical choices in this monorepo. Use when a change chooses among meaningful alternatives, moves from an ideal approach to a practical one because of discovered constraints, establishes a cross-component contract or convention, accepts a consequential trade-off, or supersedes an earlier decision. Also use before completing any non-trivial implementation thread or merge request to decide whether its work produced an ADR-worthy decision.

Record Architecture Decisions

Capture why a decision made sense with the constraints and evidence available at the time. Keep the record useful after those constraints change.

Evaluate the change

1. Review the conversation, implementation attempts, test results, and diff for durable decisions.
2. Write an ADR when the work:
   • chose among meaningful alternatives;
   • abandoned a preferred design because evidence exposed a constraint;
   • established a convention, dependency, interface, data model, deployment pattern, or operational policy;
   • accepted a trade-off that a future maintainer may otherwise undo without understanding it; or
   • changes a decision documented by an existing ADR.
3. Skip an ADR for routine maintenance, implementation details, straightforward bug fixes, and choices already dictated by an accepted ADR.
4. If no ADR is needed, state that explicitly in the final handoff.

Write the ADR

1. Read docs/adr/README.md and docs/adr/template.md completely.
2. Create docs/adr/YYYY-MM-DD-short-title.md. Use a specific, durable title and avoid sequential numbers that conflict across concurrent branches.
3. Preserve the facts from the work:
   • the need or problem;
   • the constraints encountered;
   • concrete evidence such as failed approaches, validation results, limits, or links;
   • the chosen approach and meaningful rejected alternatives;
   • positive and negative consequences; and
   • conditions under which the decision should be reconsidered.
4. Keep the ADR terse and scannable:
   • Default to one or two concise bullets under each template heading.
   • Use paragraphs only when bullets would obscure necessary reasoning.
   • Combine closely related alternatives and consequences instead of cataloging every detail.
   • Preserve the decision, evidence, trade-off, and reconsideration trigger without narrating the implementation.
5. Include the ADR in the same merge request as the decision whenever possible.

Preserve history

• Do not rewrite a landed ADR to make the old decision appear current.
• Add a new ADR when a decision changes, and link the earlier record under Supersedes.
• Do not add approval or status metadata. Landing through merge request review records acceptance; an unmerged ADR remains a proposal in its branch.

template.md

Decision title

• Date: YYYY-MM-DD
• Related: issue, merge request, code, or other ADR links
• Supersedes: omit when not applicable

Context

What need prompted this decision?

Constraints and evidence

What was true at the time? Include relevant failed attempts, validation results, limits, or other evidence.

Decision

What are we doing, and why is it the practical choice?

Alternatives considered

What meaningful alternatives did we reject, and why?

Consequences

What improves, what becomes harder, and what risks remain?

Reconsider when

Which assumptions or constraints changing would justify revisiting this decision?