decision-log

---
name: decision-log
description: "Architectural decision logger. Use when making a non-obvious technical choice, selecting a library, picking between approaches, or logging anything that future sessions will need to understand retroactively."
mode: [engineering, ops]
effort: low
---

# Decision Log

## Red Flags (rationalization check)

Before deferring a decision-log entry, ask yourself — are any of these thoughts running? If yes, STOP. Unlogged decisions are lost within 2 compactions.

| Thought | Reality |
|---------|---------|
| "I'll remember why we picked this" | You won't. Future-you in 3 weeks has forgotten the alternatives. Log it. |
| "Not architectural enough to log" | Lib choice, data model, pattern = architectural. Low bar. Err on logging. |
| "The plan documents it, no need for JSONL" | Plans get archived. `.claude/decisions.jsonl` is append-only and grep-friendly. Dual-write. |
| "I'll log at session-end in retrospective" | Decisions at session-end lose context (rationale fades by evening). Log now. |
| "Alternatives field is padding" | "Rejected because" is the #1 reason future-you understands the decision. Fill it. |
| "Reversibility is obvious" | EASY / MODERATE / HARD flag guides future refactor risk calculation. State it. |
| "ATLAS_TOPIC is set, but topic memory is redundant" | Dual-write to `.claude/topics/${ATLAS_TOPIC}/decisions.md` — topic context survives branches. |

## When to Log
- Choosing between 2+ approaches
- Selecting a library/framework
- Designing a data model
- Any non-obvious technical choice
- Anything future sessions should know about

## Format

Append to `.claude/decisions.jsonl` (one JSON object per line):

```json
{
  "date": "2026-03-15",
  "subsystem": "rule-engine",
  "decision": "Use JsonLogic for rule conditions",
  "context": "Need a format that works in both Python and JavaScript for rule evaluation",
  "alternatives": [
    {"name": "Rete algorithm", "rejected_because": "Overkill for 500 rules, complex to implement"},
    {"name": "Custom DSL", "rejected_because": "Maintenance burden, no ecosystem"},
    {"name": "Raw SQL conditions", "rejected_because": "Not portable, hard to build UI for"}
  ],
  "rationale": "JsonLogic is standard, RAQB exports to it natively, Python library exists",
  "source": "Context7 @react-awesome-query-builder, WebSearch 'rule engine patterns 2026'",
  "impact": "All rule conditions stored as JSONB, evaluated client and server side",
  "reversibility": "Medium — would require migrating all condition data"
}
```

## Integration with Plans
When making decisions during planning (Section C):
- Log the decision
- Reference it in the plan: "See decision log: {date} {decision}"
- Future sessions can grep decisions.jsonl for context

---

## Workspace Mode (v8.1.0+)

When ATLAS workspace is detected (`~/.atlas/runtime/workspace.json` shows `workspace` non-null), this skill ALSO proposes a MADR-format ADR file in the workspace `decisions/` directory.

This is a **TRIPLE WRITE** : `.claude/decisions.jsonl` (existing) + topic memory (existing) + workspace ADR (new).

### Process

1. Check if workspace state exists :
   ```bash
   if [ -f ~/.atlas/runtime/workspace.json ]; then
     WS_ROOT=$(python3 -c "import json; print(json.load(open('$HOME/.atlas/runtime/workspace.json'))['workspace']['root'])" 2>/dev/null)
     USER=$(python3 -c "import json; print(json.load(open('$HOME/.atlas/runtime/workspace.json'))['user']['name'])" 2>/dev/null)
   fi
   ```

2. If workspace detected, propose new MADR ADR file :
   ```bash
   NEXT_ID=$(ls "$WS_ROOT/decisions" | grep -E '^[0-9]{4}-' | tail -1 | grep -oE '^[0-9]{4}' | awk '{printf "%04d", $1+1}')
   ADR_FILE="$WS_ROOT/decisions/${NEXT_ID}-${SLUG}.md"
   ```

3. **HITL gate** : `decisions/**` is in `write_hitl` capability — use `AskUserQuestion` to confirm before writing :
   - Show preview of MADR frontmatter + sections
   - User approves/edits/rejects
   - Only on approve : write file

4. MADR template :
   ```markdown
   ---
   adr: NNNN
   title: {kebab-title}
   status: accepted
   created: {ISO 8601}
   created_by: {workspace user}
   ratified: {ISO 8601}
   ratified_by: [{user}]
   atlas_session_id: {ATLAS_SESSION_ID}
   tags: []
   ---

   # ADR-NNNN: {Title}

   ## Status
   Accepted ({date})

   ## Context
   {What prompted this decision}

   ## Decision
   {What was chosen}

   ## Alternatives Considered
   {What was rejected and why}

   ## Consequences
   ### Positive
   ### Negative
   ### Neutral
   ```

5. Audit log : entry auto-written by `workspace-audit` PostToolUse hook → `ops/audit/{YYYY-MM}/audit-{YYYY-MM-DD}.jsonl`

### Backwards compatibility

- If workspace NOT detected : skip workspace ADR, use legacy decisions.jsonl + topic memory only
- If workspace.yml capabilities don't include `decisions/**` in write_hitl : skip (defensive)
- Plugin v7.16.1 / v8.0.0 : no behavior change (this section is additive)

## Topic Memory (SP-ECO v4)

When `ATLAS_TOPIC` env var is set (topic-based session), ALSO write decisions to topic memory.
This is a **DUAL WRITE** — the existing `.claude/decisions.jsonl` write stays unchanged.

### Process

1. Check if `.claude/topics/${ATLAS_TOPIC}/` directory exists
2. If yes: append decision to `.claude/topics/${ATLAS_TOPIC}/decisions.md` in markdown format:

```markdown
## Decision: {title}
**Date**: {YYYY-MM-DD HH:MM TZ}
**Context**: {what prompted this decision}
**Choice**: {what was decided}
**Alternatives rejected**: {what was NOT chosen and why}
**Confidence**: {high/medium/low}
**Reversibility**: {easily reversible / hard to reverse / irreversible}
```

3. Append using bash:
   ```bash
   TOPIC_DIR=".claude/topics/${ATLAS_TOPIC}"
   if [ -d "$TOPIC_DIR" ]; then
     cat >> "$TOPIC_DIR/decisions.md" << 'DECISION'
   ## Decision: {title}
   **Date**: {date}
   **Context**: {context}
   **Choice**: {choice}
   **Alternatives rejected**: {alternatives}
   **Confidence**: {confidence}
   **Reversibility**: {reversibility}

   DECISION
   fi
   ```

4. Topic `decisions.md` is **markdown** (not JSONL) for human readability in topic context
5. If the file doesn't exist yet, create it with a header:
   ```markdown
   # Decisions — {ATLAS_TOPIC}
   > Topic-scoped decision log. See also: `.claude/decisions.jsonl` (global)
   ```