| name | track-decision |
| description | Record product decisions and requirements from team conversations. Use when new decisions are made, requirements change, priorities shift, or someone says "let's do X instead of Y." Triggers on "track decision", "new decision", "record this decision", "add requirement", "update requirements", "new requirement", "priority change", or when team conversation context contains a product/architecture decision that should be preserved. |
Track Decision / Requirement
Record product decisions (ADRs) and requirements from team conversations so rationale isn't lost.
When to Use
- A team conversation reveals a decision ("let's do X instead of Y")
- New product requirements come in (Slack message, meeting notes)
- Priorities change ("move X to highest priority")
- Someone asks "can you record this decision"
Instructions
Step 1: Determine What to Record
Read the conversation context. Classify what's being recorded:
- Decision → create/update an ADR in
docs/decisions/
- Requirement → update
docs/REQUIREMENTS.md
- Both → do both (a decision often implies a requirement)
If unclear, ask the user: "Is this a decision (why we chose something) or a requirement (what we need to build), or both?"
Step 2: Read Existing Docs
Always read before writing to avoid duplicates or contradictions:
docs/decisions/ # Existing ADRs
docs/REQUIREMENTS.md # Current requirements and priorities
Check:
- Does an existing ADR already cover this? → update it (or supersede it with a new one)
- Does the requirement already exist? → update priority/description, don't duplicate
- Does this contradict an existing decision? → flag to the user before proceeding
Step 3a: Create ADR (for decisions)
Find the next ADR number by listing docs/decisions/:
ls docs/decisions/
Create docs/decisions/NNN-short-slug.md using this template:
# NNN — Title (short, imperative)
Date: YYYY-MM-DD
Status: accepted
## Context
What prompted this decision? (2-3 sentences max)
Include who was involved if from a team conversation.
## Decision
What we decided. (1-2 sentences, direct)
## Consequences
What follows from this. (3-5 bullet points)
- What changes
- What stays the same
- What this enables/blocks
- Link to related ADRs if any: [ADR-NNN](NNN-slug.md)
Rules:
- Keep it short — half a page max
- Context should capture the why, not exhaustive analysis
- Link to related ADRs and tickets where relevant
- If this supersedes an existing ADR, update the old one's status to
superseded by ADR-NNN
Step 3b: Update Requirements (for requirements)
Edit docs/REQUIREMENTS.md:
- New requirement → add to the appropriate priority tier (Highest / Medium / Lower)
- Priority change → move the item between tiers, note the date
- Requirement update → modify description in place
- New "Recently Decided" entry → add at bottom if it came from a team discussion, link to ADR and ticket
Format for each requirement:
### Short title
One-paragraph description of what's needed and why.
- **Source:** Who requested, when (if from a conversation)
- **Related:** Links to ADRs, epics, tickets
- **Tickets:** Path to ticket or `—` if none yet
- **Current state:** Brief note on progress (if any)
Step 4: Cross-link
After creating/updating:
- If you created an ADR AND there's a related ticket → add the ADR link to the ticket
- If you updated requirements AND there's a related ADR → link them
- If the decision affects an existing plan → note it in the plan or flag to the user
Step 5: Confirm with User
Show the user what you created/updated:
Recorded:
- ADR-005: [title] → docs/decisions/005-slug.md
- Updated REQUIREMENTS.md: moved "X" to highest priority
Want me to adjust anything?
Handling Args
/track-decision — interactive, reads conversation context/track-decision "we decided to use X because Y" — create ADR from the quoted text/track-decision requirement "need to support Windows" — add/update requirement only/track-decision priority "move rewind to highest" — update requirement priority only
Examples
Team says "let's use SQLite instead of Postgres for local storage":
→ Create ADR explaining context (local-first tool, no server), decision (SQLite), consequences (single-file DB, no concurrent writes)
Slack message with new feature list and priorities:
→ Update REQUIREMENTS.md with new items, adjust priorities, add source attribution
"Don't drop similar screenshots" from product lead:
→ Create ADR (why: training data needs small visual changes), update requirement (variable-rate capture), link to existing ticket
