# 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

```markdown
---
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](audit-pattern.md) - Audits read and write decisions
- [Reversion Protection](reversion-protection.md) - Invariant changes require decisions