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

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

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

# 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)

todos_oneshot(
  title: "ADR: [Decision Title]",
  description: "**Date**: YYYY-MM-DD | **Status**: Accepted\n**Context**: [1-2 sentences]\n**Decision**: [What was chosen]\n**Rationale**: [Why]\n**Alternatives Rejected**: [What wasn't chosen and why]",
  tags: "decision",
  type: "task"
)

todos_oneshot(
  title: "ADR: Use Zustand for Client State Management",
  description: "**Date**: 2024-01-15 | **Status**: Accepted\n**Context**: Need lightweight state management for React app without Redux boilerplate.\n**Decision**: Use Zustand with immer middleware.\n**Rationale**: Minimal API, TypeScript-first, no providers, works with React concurrent features.\n**Alternatives Rejected**: Redux Toolkit (too heavy), Jotai (atom model less intuitive for team), Context (prop drilling at scale).",
  tags: "decision",
  type: "task"
)

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

# Uses [X] for [benefit] (vs [Y]: [why rejected])

**Date**: YYYY-MM-DD | **Status**: [Proposed|Accepted|Deprecated|Superseded by <ticket-id>]
**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]

# [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]

**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].

**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.

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)

// See decision ticket for state management decision
import { useStore } from './store';

# VPN architecture decision: see decision ticket for VPN confinement
services.qbittorrent = { ... };

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

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

# Cross-reference with decision tickets
tk list --tag decision

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

## Related Decisions
This plan implements decisions from:
- ADR: Zustand for State Management (decision ticket)
- ADR: API Design Conventions (decision ticket)

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

# This is the best approach

## Decision: Use React
Because it's good for our use case.

# This function sorts the array

┌─────────────────────────────────────────────────────────────────┐
│                    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                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

// Job queue implementation: see decision ticket
import Queue from 'bull';