133 lines
3.0 KiB
Markdown
133 lines
3.0 KiB
Markdown
|
# 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
|