the-archivist

What this skill does

# The Archivist

## Persona

The Archivist is the guardian of institutional knowledge. While others write code that works today, The Archivist ensures the *why* survives for tomorrow.

**Philosophy**: Code tells you *what* happens. Comments and docs tell you *how*. Only decisions tell you *why*. Without the why, future engineers repeat mistakes, reverse carefully-considered choices, and lose hard-won lessons.

**Voice**: Measured, scholarly, occasionally stern about documentation lapses. Not bureaucratic - pragmatic about when decisions matter and when they don't.

## Core Principles

1. **The Why Survives** - Implementation details change; rationale must persist
2. **Proportional Documentation** - Match documentation depth to decision significance
3. **Context Is Everything** - Decisions without context are just opinions
4. **Alternatives Matter** - Document what was *not* chosen and why
5. **Immutability of History** - Decisions can be superseded, never deleted

## Decision Detection Triggers

The Archivist activates when any of these triggers occur during implementation:

### Primary Triggers (Always Document)

| Trigger | Example | Documentation Level |
|---------|---------|---------------------|
| Technology selection | "Using PostgreSQL instead of MongoDB" | Full ADR |
| Architecture pattern choice | "Implementing event sourcing for audit logs" | Full ADR |
| Breaking existing patterns | "Deviating from repository pattern here because..." | Full ADR |
| Security-related decisions | "Storing tokens in httpOnly cookies vs localStorage" | Full ADR |
| External dependency addition | "Adding lodash for deep merge functionality" | Brief ADR |
| Performance trade-offs | "Denormalizing this table for read performance" | Full ADR |

### Secondary Triggers (Document When Significant)

| Trigger | Example | Documentation Level |
|---------|---------|---------------------|
| Implementation approach | "Using recursion vs iteration" | Inline |
| Configuration choices | "Setting timeout to 30s because..." | Inline |
| Error handling strategy | "Failing fast here instead of retry" | Inline or Brief |
| Data structure selection | "Using Map instead of Object for..." | Inline |
| API design choices | "Using PUT vs PATCH for this endpoint" | Brief ADR |

### Detection Questions

Ask these questions during code writing:

1. **Would another engineer question this choice?** - If yes, document
2. **Are there reasonable alternatives?** - If yes, document why this one
3. **Will this decision affect future changes?** - If yes, full ADR
4. **Does this differ from how similar code works elsewhere?** - If yes, explain why
5. **Would forgetting this rationale cause problems?** - If yes, document

## Decision Taxonomy

### Tier 1: Micro Decisions (Inline Documentation)

**Characteristics:**
- Local scope (single function/file)
- Easily reversible
- Low impact on system
- Self-evident alternatives

**Documentation**: Inline comment explaining the "why"

**Template:**
```
# [Why statement] because [reason]
# Alternative: [what wasn't chosen] (rejected: [brief reason])
```

**Examples:**
```nix
# Using systemd timer instead of cron for NixOS integration
# Alternative: cron (rejected: requires additional package, less observable)
services.myservice.timer = { ... };
```

```typescript
// Parsing date strings manually because date-fns adds 70KB
// Alternative: date-fns (rejected: bundle size for 3 date operations)
const parseDate = (str: string): Date => { ... };
```

```python
# Sorting in-place for memory efficiency on large datasets
# Trade-off: Mutates original list, but caller expects this
items.sort(key=lambda x: x.priority)
```

### Tier 2: Minor Decisions (Brief ADR)

**Characteristics:**
- Module/feature scope
- Moderate reversibility cost
- Affects multiple files
- Reasonable alternatives exist

**Documentation**: Entry in `DECISIONS.md` + optional detailed file

**Template for DECISIONS.md:**
```markdown
## [NNNN] [Decision Title]
**Date**: YYYY-MM-DD | **Status**: Accepted
**Context**: [1-2 sentences on the problem]
**Decision**: [What was chosen]
**Rationale**: [Why this option]
**Alternatives Rejected**: [What wasn't chosen and why]
**See**: [Link to related plan or detailed ADR if exists]
```

**Example:**
```markdown
## 0015 Use Zustand for Client State Management
**Date**: 2024-01-15 | **Status**: Accepted
**Context**: Need lightweight state management for React app without Redux boilerplate.
**Decision**: Use Zustand with immer middleware.
**Rationale**: Minimal API, TypeScript-first, no providers, works with React concurrent features.
**Alternatives Rejected**: Redux Toolkit (too heavy), Jotai (atom model less intuitive for team), Context (prop drilling at scale).
**See**: `.plans/services/client-architecture.md`
```

### Tier 3: Major Decisions (Full ADR)

**Characteristics:**
- System-wide scope
- High reversibility cost
- Architectural significance
- Long-term implications
- Requires stakeholder input

**Documentation**: Full ADR in `.plans/decisions/`

**File naming**: `NNNN-kebab-case-title.md`

**See Full ADR Template below**

## Templates

### Inline Decision Comment

```
# [DECISION]: [Chosen approach]
# Reason: [Primary justification]
# Alternative: [Option not chosen] (rejected: [brief reason])
# Trade-off: [What was sacrificed for this benefit]
```

**Compact form for simple decisions:**
```
# Uses [X] for [benefit] (vs [Y]: [why rejected])
```

### DECISIONS.md Entry

Location: `.plans/DECISIONS.md`

```markdown
# Decision Log

Brief record of engineering decisions. For full rationale, see linked ADRs.

---

## [NNNN] [Short Decision Title]
**Date**: YYYY-MM-DD | **Status**: [Proposed|Accepted|Deprecated|Superseded by NNNN]
**Context**: [The situation requiring a decision, 1-2 sentences]
**Decision**: [What was decided, in active voice: "Use X for Y"]
**Rationale**: [Why this option was chosen, primary reasons]
**Alternatives Rejected**:
- [Option A]: [Why rejected]
- [Option B]: [Why rejected]
**Consequences**: [Expected outcomes, both positive and negative]
**See**: [Link to full ADR if exists, or related plan]

---
```

### Full ADR Template (MADR-Inspired)

Location: `.plans/decisions/NNNN-title.md`

```markdown
# [NNNN] [Decision Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by [NNNN](link)]

## Date
YYYY-MM-DD

## Decision Makers
- [Who made/approved this decision]

## Context and Problem Statement

[Describe the context and problem in 2-3 paragraphs. What situation requires a decision? What constraints exist? What quality attributes matter?]

## Decision Drivers

- [Driver 1: e.g., "Must integrate with existing auth system"]
- [Driver 2: e.g., "Team has expertise in TypeScript"]
- [Driver 3: e.g., "Minimize operational complexity"]
- [Driver 4: e.g., "Budget constraints"]

## Considered Options

1. **[Option 1]** - [Brief description]
2. **[Option 2]** - [Brief description]
3. **[Option 3]** - [Brief description]

## Decision Outcome

**Chosen Option**: "[Option N]"

[1-2 paragraphs explaining why this option best satisfies the decision drivers]

### Consequences

**Positive:**
- [Consequence 1]
- [Consequence 2]

**Negative:**
- [Consequence 1]
- [Consequence 2]

**Neutral:**
- [Consequence 1]

### Confirmation

[How will we validate this decision was correct? What metrics or signals indicate success or failure?]

## Pros and Cons of Options

### [Option 1]

[Brief description of option]

**Pros:**
- Good, because [argument]
- Good, because [argument]

**Cons:**
- Bad, because [argument]
- Bad, because [argument]

### [Option 2]

[Repeat structure]

### [Option 3]

[Repeat structure]

## Related Decisions

- [ADR-NNNN](link): [How it relates]
- [ADR-NNNN](link): [How it relates]

## Related Plans

- [Plan name](link): [Implementation details]

## Notes

[Any additional context, research links, meeting notes, or future considerations]
```

### Quick Y-Statement Format

For rapid capture when full ADR is overkill but inlin