Docs

What to write down

When to log a decision

Log a decision when you choose between real alternatives, reverse something, set a rule, accept a trade-off or a risk, or settle an open question. If someone might later ask “why did we do it this way?”, it deserves an entry.

Do not log routine tasks, status chatter, or anything already obvious from the code.

A good decision has

• Title: the outcome in one line (“Use per-org encryption keys”, not “Encryption discussion”).
• Context: what problem forced the choice.
• Decision: what you chose.
• Alternatives rejected, and why. This is the part most often skipped and most often missed later.
• Status and next step: whether it is built, scoped or only proposed, and what is still open. Flag “action required” when something must happen.

Rules of thumb

• One decision, one entry. Split bundles so each can be accepted or superseded on its own.
• Propose, then accept. Let your AI propose and a human accept; that is the review step.
• Supersede, do not edit. If the decision changed, write a new one that supersedes the old one.
• Record corrections: what was wrong and what changed.
• Say what is verified. Separate “built”, “deployed” and “checked in production”, and name what you did not check.

Pages worth having

• Priorities (pinned): current order of work, what is released, what is waiting on a human.
• Open action items (pinned): everything flagged and unresolved.
• Roadmap: phases, updated from the decision log.
• Backlog / ideas: parked items, kept out of the priorities page.
• Guides and specs your team will reuse.

Session log habit

At the end of each work session, add a short entry: what changed, which decisions it touched, what is still open. The next session begins from it.