tools-only State Management
Purpose: Persistent memory across sessions - decisions, blockers, learnings.
Structure
Output: .specs/project/STATE.md
# State
**Last Updated:** [ISO timestamp]
**Current Work:** [Feature name] - [Task identifier]
---
## Recent Decisions (Last 60 days)
### AD-[NNN]: [Decision title] ([date])
**Decision:** [What was decided]
**Reason:** [Why this choice]
**Trade-off:** [What was sacrificed]
**Impact:** [How this affects implementation]
### AD-[NNN]: [Decision title] ([date])
[Same structure]
---
## Active Blockers
### B-[NNN]: [Blocker description]
**Discovered:** [Date]
**Impact:** [Severity and scope]
**Workaround:** [Temporary solution if available]
**Resolution:** [Path to permanent fix]
---
## Lessons Learned
### L-[NNN]: [Learning description]
**Context:** [Situation that occurred]
**Problem:** [What went wrong]
**Solution:** [How it was resolved]
**Prevents:** [What this knowledge prevents in future]
When to Update
| Event | Action |
|---|---|
| Significant architectural choice | Add AD-[NNN] |
| Implementation blocked | Add B-[NNN] |
| Important discovery/learning | Add L-[NNN] |
| Session end | Update "Last Updated" + "Current Work" |
Size Management (Hybrid Strategy)
Zones:
- 🟢 <7k tokens: No action
- 🟡 7-10k tokens: Footer note "STATE.md at [X]k. Cleanup recommended."
- 🔴 >10k tokens: Active prompt "STATE.md critical ([X]k). Cleanup now?"
Cleanup process:
- Move decisions >60 days to STATE-ARCHIVE.md
- Keep only active blockers
- Preserve recent learnings (<60 days)
Validation:
- Decisions have clear rationale?
- Blockers include resolution path?
- Learnings are actionable?
Preferences
Track user-facing behavioral state in STATE.md:
## Preferences
**Model Guidance Shown:** [ISO date or "never"]
Update when:
| Event | Action |
|---|---|
| First model tip given | Set date |
| User acknowledges/dismisses | Keep date (don't repeat) |
This prevents repetitive suggestions while maintaining natural, helpful behavior.