Record engineering decision

Record an engineering decision

Capture the smallest durable decision that will change future implementation, review, migration, or operational choices.

1. Decide whether a record is warranted

Create or update a record only when the decision is accepted and at least one applies:

• it establishes or changes architecture ownership or dependency direction;
• it changes a public, persisted, security, data, deployment, or operational contract;
• it adopts or rejects a material dependency or platform strategy;
• a future maintainer could reasonably reopen the same tradeoff without this context;
• it supersedes a previous durable decision.

Do not record routine implementation details, speculative options, task status, raw incident logs, or facts already owned by a stronger canonical document.

2. Find the repository convention

Inspect active AGENTS.md, contribution guidance, documentation indexes, and existing ADR or decision directories. Reuse the repository's naming, numbering, status vocabulary, and template.

When no convention exists, copy assets/DECISION.template.md to:

docs/decisions/YYYY-MM-DD-<short-kebab-title>.md

Create only the target record and the minimum directory/index update needed to make it discoverable.

3. Ground the record in evidence

Separate observed facts from interpretation. For material runtime or external evidence, record:

• source and environment;
• observation time or time window;
• stable artifact, query, issue, trace, or correlation reference when available;
• freshness and redaction notes;
• whether the statement is verified fact, inference, or unresolved uncertainty.

Reference durable repository paths, tests, schemas, manifests, or sanitized artifacts. Never copy credentials, personal data, proprietary payloads, or raw logs merely to make the record self-contained.

4. Write the decision, not a meeting transcript

Complete the template with:

• context and constraints;
• the decision and its owning boundary;
• serious alternatives and why they were rejected;
• positive, negative, and operational consequences;
• verification and revisit triggers;
• superseded or superseding records.

State unknowns honestly. Evidence provenance improves auditability; it does not prove the conclusion true.

5. Connect guidance without duplication

If future agents must consult this decision, add one concise pointer to the nearest appropriate user-owned AGENTS.md section or canonical documentation index. Do not paste the record's rationale into AGENTS.md, and never edit a generated managed block directly.

6. Verify and report

Check links, naming, status, dates, referenced paths, redaction, and compatibility with the repository convention. Run the repository's documentation or validation command when available.

Report the decision path, status, key consequence, verification, and any unresolved evidence gap. Do not claim that recording a decision enforces it; source, schemas, tests, Rules, CI, and runtime controls remain the executable boundaries.