how to log decisions so future-you can audit them

TL;DR

Log every significant decision as: context, options considered, decision, reason, and date; one paragraph each, in a running file. Future-you will not remember why, and "why" is the part that matters when revisiting. The log pays off the first time a decision gets questioned and you answer from the record instead of from memory.

how to log decisions so future-you can audit them

Use this when

• You make judgment calls others will revisit
• A decision got questioned months later and nobody remembered why
• You are handing work to a successor or a future agent run
• You want architecture decision records without the ceremony
• You need to show your work to a founder or auditor

Not for this skill when

• You need formal ADRs for a large org (use the ADR format; this is the lightweight cousin)
• The decision is trivial or easily reversible (do not log what does not matter)
• You need meeting minutes (different document)
• You are tracking tasks, not decisions (different log)

Steps

1. Create one running decision log file. Dated entries, newest at top or bottom (pick one), each entry short. A single file beats a folder of files; the value is in scanning the history, and scanning needs one place.

   decisions.md: [date] title / context / options / decision / reason

Expected output: the file exists with the format. Success check: you can find a decision from three months ago in under a minute.

1. Capture the five fields for each significant decision: date, context (what forced the call), options considered (at least two, or note why there was only one), the decision, and the reason. The reason is the field future-you needs; "we chose X" without "because Y" is archaeology, not a log.

   date: [date]
   context: [what forced the decision]
   options: [A, B, (C)]
   decision: [what was chosen]
   reason: [why, in one paragraph]

Expected output: complete entries. Success check: a stranger can reconstruct your reasoning from the entry alone.

1. Log the decision when you make it, not later. Memory edits: options you dismissed start looking obviously wrong, and the real tradeoffs fade. Same-day logging captures the honest uncertainty, which is precisely what the audit needs.

   [ ] entry written the day the decision was made

Expected output: same-day entries as a habit. Success check: no entry is reconstructed weeks later from memory.

1. Note what would change the decision. The tripwire that reopens it: "revisit if X". Decisions are bets; writing the falsifying condition turns future revisits from arguments into checks.

   revisit if: [condition that would change the call]

Expected output: tripwires on major decisions. Success check: at least one past decision got revisited because its tripwire fired.

1. Review the log quarterly and prune nothing. Read it for patterns: are the same decisions recurring (decide once, make it policy), are reasons holding up, are tripwires firing unnoticed. The log is a mirror; the review is looking into it.

   quarterly review: patterns [list], new policies [list]

Expected output: dated review notes. Success check: at least one recurring decision became a policy this year.

Variant phrasings

Lightweight architecture decision records

ADR phrasing. This skill is ADRs without the template ceremony; steps 1 and 2 are the format.

How to document why you did something

Why phrasing. Step 2's reason field is the answer; the rest is scaffolding to make the reason findable.

Decision journal for founders

Founder phrasing. Same log, framed as a personal practice; the tripwire in step 4 is the most valuable field.

Handoff documentation for agents

Handoff phrasing. The decision log is what lets the next agent (or the next you) continue without re-deriving everything.

Why it happens

Decisions are made under uncertainty, then the uncertainty resolves and hindsight rewrites the story: the chosen option looks obvious, the rejected ones look foolish, and the real tradeoffs vanish. The log preserves the decision as it looked from inside the uncertainty, which is the only view that helps the next decision. "Revisit if" conditions work because most decisions are conditional bets, and conditions change.

Edge cases / pitfalls

• Logging everything is logging nothing. Reserve the log for decisions that would be hard to re-derive; routine calls stay in the task tracker.
• Do not edit old entries to look smarter. Append corrections as new entries; the log's credibility depends on it being a record, not a narrative.
• Shared logs need shared honesty. If the log becomes performance art for stakeholders, people stop writing the real reasons; keep an honest private layer if the public one must be polished.
• The log is not a substitute for communicating the decision. Tell the affected people now; the log is for the future audit, not the present announcement.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gpWwyiP0vmmnxVIu2qjHaQ