ADR-lite Format
Every decision follows a compact structure:
| Section | Description |
|---|---|
| Context | Why this decision is needed |
| Decision | What was decided |
| Why | Single strongest reason |
| Over | Max 3 alternatives considered |
| Means | Consequences and affected areas |
For complex decisions, an extended format adds a Trade-offs section.
Smart Features
Auto-Infer Alternatives
If you only state the decision, AI infers 1-2 common alternatives:
/note-decide Use PostgreSQL for the user serviceAI adds: Over MongoDB, MySQL — because those are the common alternatives for a database choice.
Decision Chains
The system searches existing decision notes. If your new decision replaces an old one, it creates a “Supersedes” link:
Supersedes: "Use MongoDB for user service" (Feb 10)This builds a decision history you can trace back.
Duplicate Detection
Before creating a new note, /note-decide searches for related prior decisions and warns you if a similar decision already exists.
Title Guidelines
Good titles are actionable and specific:
- “Use JWT for auth” (not “Authentication”)
- “Deploy to Fly.io” (not “Deployment”)
- “Switch from REST to GraphQL” (not “API”)
When to Use /note-decide
Use this when you want to record why you chose something, not just what you chose. The decision log becomes invaluable when:
- A new team member asks “why did we do it this way?”
- You need to revisit a decision months later
- You want to track how your architecture evolved