Decision Documentation Skill

Decision Documentation Skill

Records architectural (ADR) and business logic (BIZ) decisions to DECISIONS.md.

When to Use

• Making an architectural choice (framework, pattern, structure)
• Defining business logic rules (calculations, limits, behavior)
• Choosing between multiple valid approaches
• After debugging reveals a non-obvious behavior requirement

Decision Types

Workflow

1. Determine Next Number

Read DECISIONS.md and find highest ADR-NNN or BIZ-NNN number:

grep -E "^### (ADR|BIZ)-[0-9]+" DECISIONS.md | tail -1

Use next number in sequence (project uses single sequence for both types).

2. Determine Date Section

Decisions are grouped by date. Check if today's date section exists:

• If yes: Add under existing date header
• If no: Create new date section at TOP (after template, before previous entries)

3. Add Decision Entry

Format (add at TOP of decisions, newest first):

## YYYY-MM-DD: {Category}

### {ADR|BIZ}-NNN: {Title}

**Context:** What situation prompted this decision?

**Options considered:** (if applicable)
1. Option A - description
2. Option B - description

**Decision:** What was decided?

**Reasoning:** Why this choice?

4. Commit

git add DECISIONS.md
git commit -m "docs: add {ADR|BIZ}-NNN {short-title}"

Examples

Architecture decision:

### ADR-010: Use Svelte Stores for State

**Context:** Need to share vehicle data between components.

**Decision:** Use Svelte stores (not context or props drilling).

**Reasoning:** Stores are simpler, reactive, and match existing patterns in codebase.

Business logic decision:

### BIZ-012: Round Consumption to 2 Decimal Places

**Context:** Display precision for l/​100km values.

**Decision:** Always round to 2 decimal places for display.

**Reasoning:** Matches Excel output and is sufficient precision for legal documents.

Notes

• Keep entries concise - future you needs quick scanning
• Always include reasoning - the "why" matters most
• Link to tech debt if decision creates known limitations
• Use "Options considered" only when multiple approaches were evaluated