Decision log

Decision log

Invocation: user only. Decision log entries are public artifacts — always confirm before publishing.

The format matches team-core/CLAUDE.md so anyone on the team can scan a decision in 30 seconds and know what we decided, why, and what would make us reconsider.

Workflow

1. Understand the decision

From $ARGUMENTS plus any recent context, identify:

• The decision itself — what we decided, not what we considered
• When — date of the decision
• Who decided — the owner (usually but not always the CEO)
• What forced it — the trigger: a deadline, a customer ask, a compliance requirement, a strategic shift, a new piece of evidence

If the user just says "log this decision" without context, pull recent Slack threads, Fathom meeting summaries, and Notion pages referencing the topic to reconstruct context. Confirm the summary with the user before proceeding.

2. Draft the entry

Exact format (matches CLAUDE.md — don't improvise):

## <one-line title in decisive voice>

- **Date:** YYYY-MM-DD
- **Owner:** <person>
- **Context:** <2-3 sentences. What forced the decision. Include the evidence or pressure that made this necessary.>
- **Decision:** <what we decided, stated as a call, not a recommendation>
- **Alternatives considered:** <bullets — each with a one-line reason it was rejected>
- **Revisit by:** <a date OR a trigger condition OR "not planned">

Title voice: "Move primary datastore from MySQL to Postgres" not "Considering a possible migration to Postgres." A decision is a commitment; write it that way.

Context is evidence, not narrative. Bad: "We've been discussing this for a while." Good: "Three of the last five incidents traced to MySQL's JSON column performance under our current query load; Postgres benchmarks at 4× throughput on the same schema."

Alternatives: at least two, with honest rejection reasons. "We considered X, rejected because Y" — not "X was inferior."

Revisit by is either a specific date, a specific trigger ("if we hit 50k concurrent users"), or "not planned" (for truly one-way decisions). "When appropriate" is not a valid answer.

3. Confirm and publish

Show the draft. Common edits:

• Title sharpened
• Context evidence tightened
• Alternatives reframed to be honest about why they lost

On approval:

1. Append to the team's decision log in Notion (default path from CLAUDE.md; ask if unset)
2. If the decision materially affects an in-flight spec or roadmap item, offer to draft a Slack post to the relevant channel linking to the decision
3. Return the Notion link

Don't

• Don't publish without approval, even if the user earlier described this as "just logging."
• Don't list alternatives the team never seriously considered. A decision log isn't a thought-bubble record; it's a justification artifact.
• Don't hedge the decision line. "Decision: we decided to proceed with Postgres pending further review" is a recommendation, not a decision. Write: "Decision: primary datastore is Postgres effective Q3."
• Don't include sensitive compensation, personnel, or legal detail unless the user explicitly confirms the distribution is appropriate for that content.