| name | task-management-loop |
| description | Task management and self-improvement loop using tasks/todo.md (checkable items, milestones, risks, verification, rollout) and tasks/lessons.md (mistake → cause → prevention → future rule after every user correction). Use at the start of any non-trivial work (create/update todo.md), during work (mark progress, add notes), at completion (verification evidence, lessons learned, remaining debt), and after ANY user correction (append to lessons.md). |
Task Management Loop
Two Files, One Loop
| File | Purpose |
|---|
tasks/todo.md | Active plan — checkable tasks, milestones, risks, verification |
tasks/lessons.md | Permanent memory — every user correction becomes a rule |
tasks/todo.md Format
# <Feature / Workstream Name>
## Milestones
- [ ] M1 — <architectural milestone>
- [ ] M2 — <architectural milestone>
## Tasks
### M1
- [ ] T1.1 — <atomic task> · file: `path/to/file.py`
- [ ] T1.2 — <atomic task> · depends: T1.1
- [ ] T1.3 — verify: `pytest tests/foo -v`
## Risks
- R1 — <risk> · mitigation: <strategy>
## Verification
- [ ] All tests pass: `pytest tests/`
- [ ] Lint clean: `ruff check .`
- [ ] Frontend build: `npm run build`
## Rollout
1. Land behind feature flag
2. Validate in staging
3. Enable in prod with monitoring
---
## Notes
<implementation notes, decisions, surprises>
## Review Summary
<at completion: what shipped, verification evidence, lessons, debt>
During Work
- Mark items
[x] immediately upon completion (do not batch)
- Add implementation notes inline under the relevant task
- If approach changes, append a "Decision:" note explaining why
- Note blockers as new
Risks entries
At Completion
Under ## Review Summary include:
- Shipped: comma-separated list of what landed
- Verification: test results, lint output, build logs (paste counts/timestamps)
- Lessons learned: what surprised you
- Remaining debt: known TODOs that didn't fit this iteration
tasks/lessons.md — Self-Improvement Loop
After ANY correction from the user, append a new entry:
## YYYY-MM-DD — <short title>
**Mistake:** <what was wrong>
**Why it happened:** <root cause — assumption, missing context, bad pattern>
**Prevention:** <concrete change to behavior or process>
**Future rule:** <one-line rule to follow going forward>
When to Append
- User says "actually, do X instead"
- User points out a bug, regression, or missed requirement
- A verification step caught something that should have been planned for
- A design choice turned out to be wrong in review
Before Starting Future Work
- Read
tasks/lessons.md (or scan recent entries)
- Identify rules that apply to the new task
- Proactively avoid the documented mistakes
Anti-Patterns
- Treating
todo.md as a TODO graveyard (stale, unused)
- Batching status updates instead of marking complete in real time
- Letting
lessons.md go unwritten after corrections (loop breaks)
- Vague lesson entries ("be more careful") — must be concrete and actionable
- Duplicating with the
TodoWrite tool — tasks/todo.md is the human-readable artifact; TodoWrite is the session-local working set
