Stop re-litigating decisions you already made.
A running log where each entry captures the decision, the context, the options, the why, and when to revisit.
Inside: The five-field entry, searchable records, and revisit triggers.
Install it in one line, or paste it in.
~/.claude/skills/ and runs automatically when it is relevant.Connect your context. Set it to your motion.
it appends entries as numbered markdown files you can grep, diff, and review.
the log lives where the rest of the project context lives.
decisions logged here feed straight into orientation for the next session.
This was built for an operator who makes real calls and hates re-arguing them. Set these to your setup:
The five fields are fixed. Where the log lives and how entries are numbered are yours.
| Set this | What it is | Default / Example |
|---|---|---|
| LOG_HOME | where entries live | a git repo/decisions; a notes tool |
| ENTRY_FORMAT | one file per entry, or one running doc | numbered markdown files |
| ID_SCHEME | how entries are numbered | 00010002... (zero-padded) |
| STATUS_SET | the states an entry can hold | proposedacceptedsuperseded |
| REVISIT_DEFAULT | default revisit trigger | "revisit if the constraint changes" |
| SUPERSEDE_LINK | how a reversal points back | new entry links the one it replaces |
Everything the skill does, in full.
Captures a decision the moment it is made, in a form future-you can search and trust. Each entry names the decision, the context that made it necessary, the options on the table, the reason one won, and the condition that should make you revisit it. Six months from now, when someone asks "why is it built this way," the answer is one grep away instead of a debate. It writes one entry at a time and never touches the log without your go-ahead.
- 1The five-field entry (fixed)
Every entry carries exactly these, in order.
- Decision what was decided, in one sentence, stated as done.
- Context the situation and constraint that forced a choice.
- Options considered the real alternatives, including the one you rejected and why.
- Why the reason this option won over the others.
- Revisit when the condition that should reopen this, a date, a threshold, an event.
- 2One entry at a time
Each call gets its own entry. The skill does not batch a week of decisions into one blob. One decision, one greppable record, one number.
- 3Greppable by design
Plain markdown, consistent headings, a stable ID. So
grep routingacross the log finds every decision that ever touched routing, in seconds, forever. - 4Supersede, never erase
When a decision is reversed, you do not delete the old entry. You write a new one that links back and marks the old one superseded. The trail of why-we-changed-our-mind is as valuable as the decisions themselves.
- 5Revisit triggers
Every entry ends with a condition to revisit, not a vague "someday." "Revisit when volume passes 10k/day" is a trigger. "Revisit later" is not.
- Nothing is written to the log without your explicit approval. The skill drafts the entry and shows it; you decide if it lands.
- No entry ships without all five fields. An entry with no "options considered" is not a decision record, it is a note.
- A superseded decision is linked, never deleted. History stays intact.
- The revisit condition is concrete, an event or a threshold, not "later."
DECISION 0007 · Route onboarding by company size · status: accepted DECISION New signups are routed to an owner by company-size band, not by persona. CONTEXT Persona routing mis-assigned ~1 in 3 signups. The team lost trust in the queue and started hand-sorting, which defeated the automation. OPTIONS CONSIDERED - Persona match (rejected: too noisy, data was sparse on new signups). - Company-size band (chosen). - Round-robin (rejected: ignores fit entirely). WHY Size band is reliably present on a fresh signup; persona is not. Fewer inputs, fewer ways to be wrong. REVISIT WHEN Persona data coverage on new signups passes ~80%, or volume passes 10k/day. (draft, not saved. approve to append as 0007 in the log)
Where an operator takes this next.
The read is step one. Here is where an operator takes it once the manual version proves out.
The log is only useful if it gets read back. Automate the reading, not just the writing.
Connect a GitHub repo so approved entries write as numbered markdown files automatically, no copy-paste step.
Schedule a Claude task to grep the log monthly for any entry whose revisit condition has likely been met, and flag it in Slack.
Wire the decision log into a context-pack or handoff so a new session opens already knowing what was decided and why.
One skill is the on-ramp.
A single skill does one job. Chained into a playbook, or run as a full build, it becomes a system. Here is where this one plugs in.