| name | decision-log-entry |
| description | Record a team decision with reasoning, options, and tradeoffs. Two variants — full entry for debated decisions, quick entry for fast ones. Saves ~25 minutes the next time someone asks "why did we choose X?" |
Decision Log Entry
Record a team decision with full reasoning. Takes ~2 minutes. Saves ~25 minutes every time someone asks "why did we choose X?"
When to Use
After any meeting where the team made a decision. If someone might ask "why did we do it this way?" in three months, log it.
Two variants:
Full entry — for decisions the team debated with multiple options. Use the full template below.
Quick entry — for fast decisions that didn't involve formal deliberation. Use the quick template.
Input
Provide:
- What was decided
- What other options were considered (if any)
- Why this option won
- What you gave up by choosing it
- Who was in the room
Can be dictated, typed, or extracted from meeting notes/transcript.
Full Entry Format
Save to: product-development/product/decisions/{YYYY-MM-DD}-{topic-slug}.md
# [Decision Title — verb + noun, e.g., "Chose Usage-Based Pricing"]
**Date:** [YYYY-MM-DD]
**Decided by:** [Names from team roster]
**Status:** Active | Superseded by [link] | Reversed on [date]
## Options Considered
1. **[Option A]** — [One sentence: what it involved and why it was attractive]
2. **[Option B]** — [One sentence: what it involved and why it was attractive]
## Decision
[Option chosen]. [One sentence on why.]
## Reasoning
[2-3 sentences expanding on the why. Include data, customer feedback, or technical constraints if available.]
## Tradeoff Accepted
[What you gave up. Be specific.]
## Revisit Conditions
[Under what circumstances should this decision be reconsidered? E.g., "If churn exceeds 5%" or "When we expand to enterprise."]
## Related
- [Link to relevant PRD, RFC, metric file, or feature-index entry]
Quick Entry Format
For decisions made quickly without formal deliberation:
# [Decision Title]
**Date:** [YYYY-MM-DD]
**Decided by:** [Names]
**Status:** Active
**Decision:** [What was decided and why, in 2-3 sentences.]
**Context:** [What prompted this decision. One sentence.]
Relationship to RFCs and PRDs
Hannah's repo logs architectural rationale in RFCs and design rationale in PRDs. We add a decisions/ folder for decisions that don't fit either — pricing, GTM, scoping, prioritization, vendor selection. If your decision is purely architectural, log it in engineering/rfcs/{area}/{slug}-rfc.md instead.
Hindsight Notes (Add as the Decision Ages)
Decisions get a ## Hindsight section appended over time as the team learns whether the call was right. Examples:
## Hindsight
- 2026-05-20 (3 months in): The assumption that competitor X would stay ecosystem-locked is starting to break. They shipped an open API. Revisit revisit-conditions if their adoption accelerates.
- 2026-08-01 (6 months in, outgoing PM): Watched the cost ratio settle at 18x, not the 22x we modeled. Tier B's pricing should be re-tuned. Successor should review.
Run the pm-handoff workflow at product/workflows/pm-handoff/ before a PM departure — it sweeps recent decisions and prompts hindsight notes.
Same-Day Decisions
If two decisions land on the same day, file names like 2026-05-06-vendor-x.md and 2026-05-06-launch-delay.md don't collide because the slugs differ. If two decisions on the same day would have overlapping slugs, append a 2-digit sequence: 2026-05-06-pricing-01.md, 2026-05-06-pricing-02.md. Before writing, ls the decisions folder for files matching the date prefix to detect collisions.
Forward References
If your decision cites a file that hasn't been written yet (a customer-call summary about to be filed, a PRD scoped but not started), don't fabricate the link. Use a [PENDING:] marker so future readers know it's intentional, not broken:
## Related
- [PENDING: customers/accounts/acme/calls/summaries/2026-05-06.md] — call that prompted this decision
- `../PRDs/billing/example-feature-prd.md`
The /freshness-check skill flags [PENDING:] markers older than 14 days so they don't rot indefinitely.
Rules
- Full entries: under 200 words. Quick entries: under 75 words. This is a log, not a doc.
- Always include at least 2 options in full entries. If the team didn't consider alternatives, note: "No alternatives formally considered — fast decision based on [reason]." Or use the quick entry format.
- After saving, append to the bottom of the "Recent Decisions" list in
product-development/product/decisions/CLAUDE.md (one bullet per line, one decision per bullet). Don't insert in the middle — that creates merge conflicts when two PMs file decisions the same day. If you hit a merge conflict on the index, keep both bullets and re-sort by date+sequence.
- The "Reasoning" section must answer WHY, not WHAT. "We chose X" is not reasoning. "We chose X because our cost ratio is 22x" is reasoning.
- When a decision is reversed or superseded, don't delete the old entry. Update its Status field to "Superseded by [link to new decision]" or "Reversed on [date] — see [link]". The history of why we changed our minds is as valuable as the original decision.
- Use the team roster from root CLAUDE.md for the "Decided by" field. If someone not on the roster was involved, add their role: "[Name], VP Sales (not on core team)."
