3.0 KiB

Raw Blame History

Decisions Record Pattern

Capture and persist decisions made during audits and reviews.

Purpose

Prevent re-litigating settled decisions. Create institutional memory for tools.

Directory Structure

<tool-root>/
  .decisions/
    2026-01-15-description-formula.md
    2026-01-18-routing-depth.md
    2026-01-20-golden-example-update.md

Decisions live in the tool's .decisions/ directory, committed to version control.

File Format

---
date: 2026-01-20
context: audit / review / modification
decision_type: invariant_change / pattern_adoption / exception
---

# [Decision Title]

## Context

What prompted this decision? What audit or review surfaced it?

## Options Considered

1. **Option A:** Description. Trade-offs.
2. **Option B:** Description. Trade-offs.
3. **Option C:** Description. Trade-offs.

## Decision

We chose **Option B** because [reasoning].

## Consequences

- Golden example X updated to reflect this
- Invariant Y modified/added/removed
- [Other impacts]

## Participants

- Human: [name/handle if known]
- AI: [model used for audit]

When to Record

Always record:

Any change to an invariant
Updates to golden examples
Adoption of new patterns
Exceptions to existing patterns
Resolutions of audit findings

Don't record:

Obvious bug fixes
Typo corrections
Formatting changes
Decisions made by user without discussion

Workflow Integration

During Audits

1. Check .decisions/ before auditing
   └─→ Load relevant prior decisions

2. Reference prior decisions in audit
   └─→ "Per decision from 2026-01-15, X is intentional"

3. Record new decisions during audit
   └─→ Write to .decisions/ before completing

During Modifications

1. Check .decisions/ for this area
   └─→ Understand why things are the way they are

2. If changing a decided behavior
   └─→ Create new decision explaining why

3. Reference chain of decisions
   └─→ "This supersedes decision from 2026-01-15"

Naming Convention

YYYY-MM-DD-<topic>.md

Keep <topic> short but descriptive:

description-formula.md
routing-depth-exception.md
golden-example-auth-flow.md

Implementation Checklist

Create .decisions/ directory in tool root
Audit workflows check .decisions/ first
Record decisions during audits (not after)
Include context, options, reasoning, consequences
Reference prior decisions when relevant
Commit decisions to version control

Anti-patterns

Decision amnesia: Not checking prior decisions before auditing. Always check first.

Over-documentation: Recording trivial decisions. Keep to substantive choices.

Orphan decisions: Decisions without context or reasoning. Future readers need the "why."

Decision conflicts: Multiple decisions on same topic without resolution. Use "supersedes" to clarify.

Cross-references

Audit Pattern - Audits read and write decisions
Reversion Protection - Invariant changes require decisions

3.0 KiB Raw Blame History