decision-log— agent skill

You are about to work on a codebase. Every significant decision you make must be logged to .decisions.md in the project root before the session ends. This is not optional. The log exists so any person — or any future Claude session — can understand why the code is the way it is without asking you.

The Problem You Are Solving

Claude makes 20 decisions building a feature. Which library to use. Why that data shape. Why not the obvious approach. What it considered and rejected. The code ships. The session ends. The reasoning is gone. The next developer — or the next Claude session — looks at the code and has no idea why anything is the way it is. They refactor the thing you specifically decided not to do. They add the dependency you specifically rejected. They ask the same questions you already answered.

The log fixes this.

What Gets Logged

Log a decision when you:

• Choose one approach over another (even briefly considered alternatives)
• Reject a library, pattern, or abstraction
• Make a tradeoff between two valid options
• Work around a constraint (technical, time, scope)
• Leave something incomplete intentionally
• Deviate from an obvious or conventional approach
• Make an assumption about requirements

Do NOT log:

• Mechanical actions with no alternative (adding a missing import, fixing a typo)
• Pure execution of an explicit user instruction with zero interpretation
• Routine boilerplate that follows the existing codebase pattern exactly

Log Format

Append to .decisions.md in the project root. Create it if it doesn't exist.

## [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 — omit if nothing was seriously considered]
**Revisit if:** [condition that would make this decision wrong — omit if not applicable]

---

Example entries

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

**What:** Vote button updates immediately in the UI before the server confirms.
**Why:** The action is low-stakes and near-instant. Waiting for server confirmation adds 200–400ms of perceived lag on every vote. Rollback on failure is acceptable.
**Rejected:** Pessimistic update (wait for server) — 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.

---

## [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 that isn't 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] Store session in cookie, not localStorage

**What:** Auth session token stored in httpOnly cookie.
**Why:** httpOnly cookies are inaccessible to JS, which eliminates XSS token theft as an attack surface. localStorage would require manual token management in every fetch call.
**Rejected:** localStorage — simpler to implement but meaningfully less secure.

---

When to Write the Log

• During the session — after each significant decision, not all at once at the end. If the session ends abruptly, partial logs are better than none.
• Before closing a task — do a final pass: did you make any decisions you haven't logged yet?
• On re-entry — if you're resuming a session, read .decisions.md first. Do not re-make decisions that are already logged.

Rules

1. One decision per entry. If you made three decisions, write three entries.
2. Write for a stranger. The reader has not seen the session. They only have the code and this file.
3. Be specific about what was rejected. "Considered other approaches" is not a log entry. Name the approach and the reason it lost.
4. Short is fine. A two-sentence entry that captures the real reason is better than a paragraph that buries it.
5. Do not edit old entries. If a decision changes, add a new entry that supersedes it. Reference the original by date and title.

On Re-entry

When starting a new session on an existing project:

1. Check if .decisions.md exists
2. If yes, read it before touching anything
3. Surface any entries marked **Revisit if:** that now apply
4. Do not contradict a logged decision without adding a new entry explaining why

One Rule Above All

If you made the decision, log it. Future you, future Claude, future teammate — they all need to know why. The code shows what. Only this file shows why.