Claude makes 20 decisions building your feature. The session ends. The reasoning disappears.

A Claude Code skill that appends a structured .decisions.md to your project after every significant choice — what was decided, why, what was rejected, and when to revisit it.

What gets logged silently during a session:

## [2026-04-06] Store session in cookie, not localStorage

**What:** Auth session token stored in httpOnly cookie.
**Why:** httpOnly cookies are inaccessible to JS, eliminating XSS token theft as an attack surface.
**Rejected:** localStorage — simpler but meaningfully less secure.

---

## [2026-04-06] Skip pagination on comments for now

**What:** Comments load all at once, no pagination.
**Why:** Current max comment count is ~40. Pagination adds complexity not justified yet.
**Rejected:** Cursor-based pagination — right call at scale, wrong call now.
**Revisit if:** Any post exceeds 100 comments or load time exceeds 500ms.

---

## [2026-04-06] Use optimistic UI for vote action

**What:** Vote button updates immediately before server confirms.
**Why:** The action is low-stakes and near-instant. Waiting adds 200–400ms of perceived lag on every vote.
**Rejected:** Pessimistic update — makes the interaction feel sluggish for a 99.9% success-rate action.
**Revisit if:** Vote fraud becomes a concern and we need server-authoritative state.

Without decision-log:

You come back the next day. Why is auth using cookies and not localStorage? Why no pagination? Why is the vote button not waiting for the server? The code doesn't say. You ask Claude. Claude has no memory of the session. You spend 20 minutes reconstructing reasoning that existed 12 hours ago.

With decision-log:

You open .decisions.md. Three entries. Two minutes. Done.

A one-shot "document your decisions" instruction produces a wall of text at the end of the session if it produces anything at all. This skill is different:

• Logs during the session, not after — each decision gets written when it's made. If the session ends abruptly, partial logs are better than none.
• Structured four-field format — What / Why / Rejected / Revisit if. Every entry answers the questions a stranger would ask looking at the code cold.
• Rejected field is required — "considered other approaches" is not a log entry. The skill forces Claude to name the alternative and the reason it lost. This is where most of the value is.
• Re-entry protocol — when Claude resumes a project, it reads .decisions.md first. It surfaces any Revisit if conditions that now apply. It does not re-make decisions already logged.
• Clear threshold for what gets logged — significant decisions only. Not "added missing import." The skill defines the line so Claude doesn't log noise or skip substance.

Option 1: Clone into skills directory

git clone https://github.com/grxkun/decision-log ~/.claude/skills/decision-log

Option 2: Copy the file directly

Download SKILL.md and place it in any directory Claude Code can read. Reference it in your CLAUDE.md:

- When building or modifying features → read `path/to/decision-log/SKILL.md`

Option 3: Use as a slash command

Create ~/.claude/commands/decision-log.md:

---
description: Build or modify code while logging every significant decision to .decisions.md
---

$ARGUMENTS

Read and follow the instructions in ~/.claude/skills/decision-log/SKILL.md

Then use /decision-log implement the auth flow in Claude Code.

Once installed, the skill auto-triggers on:

• "build this feature"
• "implement"
• "add"
• "architect"
• "set up"
• "design"
• Any task where Claude will make decisions the user needs to understand later

## [YYYY-MM-DD] [short title]

**What:** [one sentence — what was decided]
**Why:** [one to three sentences — the reasoning]
**Rejected:** [what was considered and not chosen, and why]
**Revisit if:** [condition that would make this decision wrong]

---

Rejected and Revisit if are omitted when nothing was seriously considered or no obvious revisit condition exists.

scope-guard controls what Claude touches before a session. decision-log captures why after. Run them together:

• scope-guard declares the blast radius upfront
• decision-log records the reasoning throughout
• Between them, every session is auditable

Pain documented by:

• r/ClaudeCode — context loss and session amnesia threads (2025–2026)
• "Claude Code Workflows and Best Practices" — the 0.8²⁰ = 1% compounding decision problem
• "The Ultimate Guide to Claude Code Skills" — Mikhail Shcheglov, Corporate Waters (2026)

MIT