the-archivist by aiskillstore

---
name: the-archivist
description: This skill should be used when engineering decisions are being made during code implementation. The Archivist enforces decision documentation as a standard practice, ensuring every engineering choice includes rationale and integrates with Architecture Decision Records (ADRs). Use when writing code that involves choosing between alternatives, selecting technologies, designing architectures, or making trade-offs.
---

# 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 inline is insufficient:

```markdown
**In the context of** [situation/requirement],
**facing** [concern/quality attribute],
**we decided** [decision outcome]
**and neglected** [alternatives],
**to achieve** [benefits],
**accepting that** [trade-offs/consequences].
```

**Example:**
```markdown
**In the context of** user session management,
**facing** the need for horizontal scalability,
**we decided** to use Redis for session storage
**and neglected** in-memory sessions and database sessions,
**to achieve** stateless application servers and sub-millisecond session lookups,
**accepting that** we add operational complexity and a failure dependency.
```

## Directory Structure

```
.plans/
├── DECISIONS.md             # Brief decision log with links
├── decisions/               # Full ADRs (immutable after acceptance)
│   ├── 0001-use-nixos-for-server.md
│   ├── 0002-postgres-over-mysql.md
│   └── template.md          # Copy this for new ADRs
└── services/                # Implementation plans (mutable)
    └── database-setup.md    # Plans reference decisions
```

## Enforcement Protocol

### During Code Writing

**Step 1: Decision Detection**

Before writing code that involves a choice, pause and ask:
- Is there more than one reasonable approach?
- Would a future engineer need to know *why*?
- Does this affect system behavior significantly?

If any answer is yes, document.

**Step 2: Tier Assessment**

Determine documentation level:

```
Is this a local, easily-reversible choice?
├─ YES → Tier 1 (Inline comment)
└─ NO
   └─ Does this affect multiple files or modules?
      ├─ YES → Is this architecturally significant or hard to reverse?
      │        ├─ YES → Tier 3 (Full ADR)
      │        └─ NO → Tier 2 (Brief ADR in DECISIONS.md)
      └─ NO → Tier 1 (Inline comment)
```

**Step 3: Document Before Implementing**

Write the decision documentation *before* writing the implementation code. This:
- Forces clear thinking about the choice
- Prevents "I'll document later" (you won't)
- Creates natural review point

**Step 4: Link Implementation to Decision**

After documenting, reference the decision in code:
```typescript
// See ADR-0015 for state management decision
import { useStore } from './store';
```

```nix
# VPN architecture decision: .plans/decisions/0003-vpn-confinement.md
services.qbittorrent = { ... };
```

### During Code Review

Reviewers verify decision documentation:

**Checklist:**
- [ ] New technology/dependency? ADR exists?
- [ ] Architectural pattern choice? ADR exists?
- [ ] Non-obvious approach? Comment explains why?
- [ ] Breaking convention? Justification documented?
- [ ] Trade-off made? Both sides documented?

**Review Response Template:**
```
Missing decision documentation:
- Line 45: Why PostgreSQL instead of existing MongoDB?
  → Needs ADR or brief explanation
- Line 123: Why custom retry logic vs axios-retry?
  → Needs inline comment with rationale
```

### Periodic Audit

Monthly, review recent changes for undocumented decisions:

```bash
# Find files changed in last 30 days
git log --since="30 days ago" --name-only --oneline

# Cross-reference with decisions
ls .plans/decisions/

# Look for decision keywords without documentation
grep -r "instead of\|rather than\|chosen\|decided" src/
```

## Integration Points

### With create-plan Skill

When creating plans, include decision references:

```markdown
## Related Decisions
This plan implements decisions from:
- [ADR-0015: Zustand for State Management](.plans/decisions/0015-zustand-state.md)
- [ADR-0012: API Design Conventions](.plans/decisions/0012-api-conventions.md)
```

### With review-changes Skill

Code review checks for missing documentation:

```markdown
### Decision Documentation Check
- ✅ New dependency (lodash) documented in DECISIONS.md
- ❌ Custom caching strategy undocumented (needs ADR)
- ✅ Inline comment explains retry logic choice
```

### With update-docs Skill

Decisions in `.plans/decisions/` are **immutable** - never update content, only status. If a decision changes, create a new ADR that supersedes the old one.

**Oracle preservation note**: Decision rationale is in the highest protection tier. Never delete or modify accepted ADRs.

## Verification Checklist

### Pre-Implementation

- [ ] Identified decisions requiring documentation
- [ ] Determined appropriate tier for each decision
- [ ] Checked for existing related ADRs
- [ ] Documented decisions before coding

### Post-Implementation

- [ ] All technology choices documented
- [ ] All architectural decisions have ADRs
- [ ] Inline comments explain non-obvious choices
- [ ] Code references relevant ADRs
- [ ] DECISIONS.md updated with new entries
- [ ] No "TODO: document why" comments remain

### ADR Quality Check

For each ADR:
- [ ] Context clearly explains the problem
- [ ] Multiple alternatives were genuinely considered
- [ ] Decision drivers are explicit
- [ ] Rationale connects drivers to choice
- [ ] Consequences include negatives (not just benefits)
- [ ] Status is current
- [ ] Related decisions are linked

## Anti-Patterns

### Documentation Anti-Patterns

**Too Vague:**
```
# This is the best approach
```
*Fix: Explain WHY it's best and compared to WHAT*

**Missing Alternatives:**
```
## Decision: Use React
Because it's good for our use case.
```
*Fix: List what else was considered and why rejected*

**Pure Description:**
```
# This function sorts the array
```
*Fix: Explain why this sorting approach over alternatives*

**Retroactive Rationalization:**
Writing ADRs after the fact to justify decisions already made without genuine consideration.
*Fix: Document during decision-making, not after*

### Process Anti-Patterns

**"I'll Document Later"** - You won't. Document before implementing.

**Over-Documentation** - Not every variable name needs an ADR. Use the tier system.

**Under-Documentation** - "It's obvious" - it's not, especially in 6 months.

**ADR Graveyards** - Decisions documented but never referenced. Link from code.

## When NOT to Document

Not everything needs formal documentation:

- **Trivial choices** - Variable names, exact indentation
- **Framework conventions** - Following React patterns in a React app
- **Language idioms** - Using Python list comprehension
- **Already documented** - Choice already covered by existing ADR
- **Temporary code** - Spike/prototype code (but note it's temporary)

**Heuristic**: If reverting this decision would take <5 minutes and affect <10 lines, inline comment is sufficient. If you're unsure, err on the side of documenting.

## Quick Reference Card

```
┌─────────────────────────────────────────────────────────────────┐
│                    THE ARCHIVIST QUICK REFERENCE                │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  BEFORE WRITING CODE, ASK:                                      │
│  • Would another engineer question this choice?                 │
│  • Are there reasonable alternatives?                           │
│  • Will forgetting this cause problems?                         │
│                                                                 │
│  DOCUMENTATION TIERS:                                           │
│  ┌─────────┬──────────────────┬─────────────────────────────┐  │
│  │ Tier 1  │ Inline comment   │ Local, reversible choices   │  │
│  │ Tier 2  │ DECISIONS.md     │ Multi-file, moderate impact │  │
│  │ Tier 3  │ Full ADR         │ Architectural, hard to undo │  │
│  └─────────┴──────────────────┴─────────────────────────────┘  │
│                                                                 │
│  MINIMUM VIABLE DECISION COMMENT:                               │
│  # Uses [X] because [reason] (vs [Y]: [why not])                │
│                                                                 │
│  MINIMUM VIABLE ADR ENTRY:                                      │
│  ## [NNNN] Title                                                │
│  **Date**: | **Status**: Accepted                               │
│  **Decision**: [What]                                           │
│  **Rationale**: [Why]                                           │
│  **Alternatives Rejected**: [What wasn't chosen]                │
│                                                                 │
│  DOCUMENT BEFORE IMPLEMENTING - NOT AFTER                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Example Session

**Scenario**: Implementing a background job processor

**Step 1: Detection**
"I need to choose between Bull, Agenda, and custom implementation for job queues."

**Step 2: Assessment**
- Affects multiple files? Yes (worker, scheduler, job definitions)
- Architecturally significant? Yes (core infrastructure)
- Hard to reverse? Yes (jobs, queues, Redis dependency)

**Result**: Tier 3 - Full ADR required

**Step 3: Document**
Create `.plans/decisions/0023-job-queue-implementation.md` with full template.

**Step 4: Implement**
Write code, referencing the ADR:
```typescript
// Job queue implementation: see ADR-0023
import Queue from 'bull';
```

**Step 5: Review**
Reviewer checks:
- ADR-0023 exists and is complete
- Alternatives genuinely considered
- Trade-offs documented
- Code references ADR

The decision is preserved. Future engineers will know *why*.