| name | decision-log |
| description | Records architectural and implementation decisions. Use when a significant technical decision is made, a spec is modified, or an approach changes during implementation. Creates numbered decision records in .factory/decisions/. |
Decision Logger
When a significant decision is made during development, record it.
When to Log
- A spec requirement is added, removed, or modified after approval
- A technical approach is changed (e.g., switching from polling to websockets)
- A trade-off is accepted (e.g., choosing simplicity over performance)
- A dependency is added or removed
- An architectural pattern is established
How to Log
Create a file in .factory/decisions/ with this format:
Filename: NNN-descriptive-name.md (e.g., 001-use-websockets-for-realtime.md)
Content:
# NNN: [Decision Title]
**Date:** YYYY-MM-DD
**Status:** Accepted | Superseded by NNN | Deprecated
**Relates to:** Requirement N (if applicable)
## Context
[What situation prompted this decision? 2-3 sentences.]
## Decision
[What was decided? 1-2 sentences.]
## Rationale
[Why this approach over alternatives? Key reasons.]
## Alternatives Considered
- [Alternative 1]: [Why rejected]
- [Alternative 2]: [Why rejected]
## Consequences
- [What changes as a result]
- [What trade-offs were accepted]
Process
- Check
.factory/decisions/ for the latest number
- Increment by 1, zero-pad to 3 digits
- Write the decision record
- Reference it in any related code comments if helpful
Rules
- Keep decisions concise (under 30 lines)
- One decision per file
- Never modify past decisions -- create a new one that supersedes
- Link to related requirements when applicable
