Decision logs
ADRs that ship. The format that makes future-you actually read them.
What a decision log is
A decision log (or ADR — Architecture Decision Record) is a single markdown file that captures one decision: what was chosen, what alternatives were rejected, why, and when to revisit. Lives in 07-Decisions/ in the vault, named by date and slug.
The reason it matters: decisions you don’t log get re-litigated. Three months later, someone (or some agent) surfaces the same question, doesn’t find prior work, and re-derives the answer from scratch. Sometimes they reach the same conclusion. Sometimes they reach a different conclusion and silently reverse the prior decision without realizing it.
A decision log takes 5 minutes to write at the moment of decision. It saves 5 hours of re-litigation later. The trade is one of the most lopsided in operator discipline.
The reversed-decision story
Three months into running multiple ventures, I caught myself almost re-building the agent system. The conversation started innocently — “maybe we should split the chief-of-staff into two agents” — and felt like fresh thinking. Halfway through I realized: I’d had this exact conversation with myself in March. Decided against it. Couldn’t remember why.
The March conversation was buried in chat history. The decision was made; the rationale was recorded only in passing context. If I’d kept going, I would have made an opposite decision based on the same facts I’d already weighed three months earlier.
The fix took 10 minutes. I went back, found the original SWOT, wrote it up as 07-Decisions/2026-03-29-agent-system-architecture.md with the frontmatter, options table, and revisit conditions described in this lesson. Linked it from the wiki page about my agent setup. Done.
Two months later, the question came up again. The agent read the decision log first, the conversation started from the prior conclusion, the wasted hour didn’t happen. That’s the entire ROI of the discipline.
Three ways logs fail
Even with the discipline in place, three patterns silently break the value of decision logs. Hover any card to see the diagnosis.
The undocumented decision
The narrative decision
The decision without revisit conditions
The fix in all three: structure over prose, with mandatory revisit conditions. The format is what makes the log queryable months later when the context has decayed.
The find-and-defend test
The diagnostic for whether your decision logs are doing their job: pretend you’re a new hire (or new agent) and try to defend a prior decision based only on what’s in the log.
Pretend you're a new hire / new agent reading my decision log
folder for the first time.
For each decision in 07-Decisions/:
1. Can you summarize what was decided in one sentence?
2. Can you list the alternatives that were rejected, with why?
3. Can you tell when this should be revisited?
4. Is the consequences section honest about what got harder?
Flag any decision where you can't answer all 4. That decision is
under-documented and won't survive future-you re-reading it.Forces every log to surface its weak points — usually missing alternatives or vague revisit conditions.
Four checks per log: can someone summarize the decision in one sentence, list the rejected alternatives with reasons, identify when to revisit, and read an honest consequences section?
If a log fails any of the four, future-you will fail to use it. The cheapest fix is at the moment of writing — the section that was vague when you wrote it will be impenetrable in 6 months.
Annotated transcript
A real conversation: operator catches near-reversal of a prior decision and decides to log it properly. Click any pinned annotation to expand the “why this turn matters” commentary.
Three operator turns, three agent turns. Result: the format, the triage rule, the calibration.
- operator
We almost re-built the agent system again. I caught it when I noticed someone proposing what we already decided against in March. Why does this keep happening?
- agent
Because the March decision wasn't logged in a queryable format. I can see it now in chat history if I dig — the SWOT comparison, the choice. But "chat history" isn't queryable. The decision lived as a moment, not as a record. Three months later, nobody (and no agent) finds it without searching.
The fix is a decision log: 07-Decisions/2026-03-XX-agent-system-architecture.md. Frontmatter on top, options table, revisit conditions. When the topic resurfaces, agent reads the log first; conversation starts from the prior conclusion, not from scratch.
- operator
What does a usable log look like? I don't want a wall of prose.
- agent
Frontmatter-driven. The structure makes it queryable; the prose explains the reasoning.
--- date: 2026-03-29 type: decision decision: Adopt Obsidian + Claude Code over custom Electron OS company: TruPath status: made impact: high owner: Michael Brenneman next_action: Migrate vault structure within 1 week revisit_on: Obsidian abandoned OR token costs exceed $500/mo tags: [decision, infrastructure] --- # Decision: Obsidian + Claude Code over Electron OS ## Context Three months into building a custom Electron app... ## Options Considered | Option | Upside | Risk | Cost of Delay | |--------|--------|------|---------------| | A: Continue Electron OS | Custom UI, full control | 80% scope, 5x effort | 3 more months building | | B: Obsidian + Claude Code | 80% value, 5% effort | Less customization | None — start now | ## Decision B. ## Execution Path - Day 1: Vault structure laid out - Day 7: First three ventures mapped in - Day 14: Agents migrated ## Consequences What gets easier: Memory persistence, agent reads. What gets riskier: Vendor dependency on Obsidian. ## Revisit Conditions - Obsidian sunset announcement - Token spend exceeds $500/mo (currently ~$60/mo) - Need for real-time multi-user collaboration arisesFrontmatter is queryable by Dataview and by agents. Options table makes trade-offs explicit. Revisit conditions are the staleness detector.
- operator
When do I write one? Every choice can't justify a log.
- agent
Three triggers:
1. Stakes. Decision involves real cost, time, or commitment. Refactor approach. Vendor choice. Architecture pattern. Hiring/firing.
2. Hard to reverse. Once you commit, going back is expensive. Database choice. Pricing model. Brand identity.
3. Will be re-asked. You can predict somebody (or some agent) will surface this question again in 2-3 months.
Any ONE of those triggers writes the log. Skip them all and you've usually got a routine choice — log it as a quick note in your daily but not in 07-Decisions/.
Rule of thumb: 5-10 decision logs per quarter for a serious operator. If you're writing 50/quarter, you're over-logging routine choices. If you're writing 1/quarter, you're under-logging real decisions.
The format — why each section matters
| Section | Purpose | What goes wrong if missing |
|---|---|---|
| Frontmatter | Queryable metadata — date, decision, status, impact, owner, revisit_on | Logs become file-name-only findable. No Dataview queries. Agent can’t filter by impact level. |
| Context | Why is this decision happening now? What’s the pressure? | Future-you can’t tell if conditions changed. The log becomes “we decided X” with no anchor. |
| Options Considered | Table of alternatives with upside / risk / cost-of-delay | Future-you re-litigates the rejected options. The log loses its main value — capturing the trade-off. |
| Decision | What was picked. One line. | If unclear, the log is descriptive, not authoritative. |
| Execution Path | What gets done, by whom, by when | Decision exists in vacuum. No accountability for the next-step. |
| Consequences | What gets easier; what gets riskier | The log under-states the cost. Future you won’t see the trade-off you accepted. |
| Revisit Conditions | When does this decision get reopened? | Decisions go stale silently. Either kept past usefulness or reopened without justification. |
Seven sections. Skip any one and the log degrades in a specific way. The most-skipped section is Revisit Conditions — and that’s the one that prevents stale decisions from quietly outliving their usefulness.
The skeleton — copy this and fill in
---
date: YYYY-MM-DD
type: decision
decision: <One-sentence statement of what was decided>
company: <which venture, or "Holding Company" for cross-venture>
status: pending | made | reversed
impact: low | medium | high
owner: <Name>
next_action: <First concrete step>
revisit_on: <When to reopen — date OR condition>
tags: [decision, <other relevant tags>]
---
# Decision: <Title — concept-level, mirror the YAML>
## Context
> What is happening, why now, and what pressure is driving the choice?
## Options Considered
| Option | Upside | Risk | Cost of Delay |
|--------|--------|------|---------------|
| A: <option> | <upside> | <risk> | <cost> |
| B: <option> | <upside> | <risk> | <cost> |
| C: <option> | <upside> | <risk> | <cost> |
## Decision
<What was picked. One line. State the option chosen.>
## Execution Path
- Immediate next action: <action>
- Owner: <name>
- Deadline: <date>
## Consequences
- What gets easier: <one-line>
- What gets riskier: <one-line>
- What changes elsewhere: <one-line>
## Revisit Conditions
> Specific conditions that would cause this decision to be reconsidered.
> Be concrete. "If circumstances change" is not a revisit condition.
- <Specific condition>
- <Specific condition>
## Related
- [[<wikilink to related decision>]]
- [[<wikilink to relevant context>]]
Keep it under 400 words. If it’s longer than 400, you’re writing prose instead of structure — extract the prose to a wiki page in 09-Research/ and link to it from the decision log.
Prompt kit
Three prompts for writing and maintaining decision logs. Save in your CLAUDE.md or a personal snippets file.
Pretend you're a new hire / new agent reading my decision log
folder for the first time.
For each decision in 07-Decisions/:
1. Can you summarize what was decided in one sentence?
2. Can you list the alternatives that were rejected, with why?
3. Can you tell when this should be revisited?
4. Is the consequences section honest about what got harder?
Flag any decision where you can't answer all 4. That decision is
under-documented and won't survive future-you re-reading it.Read this conversation / context: <paste or path>.
Identify the decision that was made. Draft it as a 07-Decisions/
log file using the standard format:
- Frontmatter (date, decision, status, impact, revisit_on)
- # Title
- ## Context (why now, what's driving the choice)
- ## Options Considered (table with upside/risk/cost-of-delay)
- ## Decision (what was picked)
- ## Execution Path (what gets done, by whom, by when)
- ## Consequences (what gets easier, what gets riskier)
- ## Revisit Conditions (when to reopen)
- ## Related (wikilinks to relevant pages, prior decisions)
Don't fabricate alternatives — if only one option was discussed,
say so. The point is to document what actually happened.Read this decision log: <path>.
Check the Revisit Conditions section. For each condition:
- Has it fired? (e.g., "if costs exceed $500/mo" — what's the
current cost?)
- Is it still relevant? (Sometimes conditions become outdated.)
If any condition has fired, the decision needs revisiting — open
a new decision log that references this one and updates the
choice. If none have fired, the decision stands; note that it
was checked.Apply this — log one real decision
20-minute exercise. Pick one decision from the last 30 days that has stakes. Log it.
Build your first decision log
Each step takes 3-5 minutes. Progress saves automatically.
- 01Pick a decision you made in the last 30 days that has stakes (cost, time, hard to reverse, will be re-asked).Examples: vendor pick, architectural choice, hiring decision, scope cut, pricing model.
- 02Write the log file at 07-Decisions/YYYY-MM-DD-<slug>.md.Use the skeleton from this lesson. Don't skip the options table or revisit conditions.
- 03Add a wikilink from the relevant venture folder or wiki page to this decision log.Decisions that aren't linked from anywhere are findable only by date — make them findable by topic too.
- 04Open a fresh agent session. Ask: "what did we decide about <topic>?"If the agent answers cleanly by reading the log, it's working. If it goes spelunking through chat history, the log isn't being found — fix the wikilinks or front-matter.
- 05Set a habit: every time you make a real decision, the next thing you write is the log file.Catching the moment is what makes this discipline cheap. After-the-fact logs are 5x harder to write because the context has decayed.