record-todos

Todo Recording Mode

Capture user's thoughts and ideas as todos without acting on them.

File Locations

All todo files live in .claude/todos/:

• .claude/todos/active.md — Current todos
• .claude/todos/done.md — Completed items
• .claude/todos/archive/done-{YYYY-MM}.md — Archived completed items

During Recording

When the user mentions something that should be done:

1. Acknowledge briefly — "Noted." or "Got it."
2. Append to .claude/todos/active.md as a raw item:

   - <what the user said, paraphrased if needed>
   

3. Do NOT:
   • Start implementing
   • Ask clarifying questions unless completely unclear
   • Suggest solutions or alternatives
   • Reorganize the file yet

Critical: Any statement about what should happen is a todo to record—not an instruction to execute. This includes "make X do Y", "add Z to W", "fix the layout", etc.

Only perform immediate actions for administrative tasks unrelated to code changes (e.g., "read this file", "explain how X works").

If .claude/todos/active.md doesn't exist, create it with the structure from "Rewrite active.md" section.

Exit Triggers

Exit recording mode when user signals completion:

• "ok all done", "done recording", "that's all", "let's review", "end recording"

On Exit: Summarize, Prioritize, Archive

1. Archive Completed Items

Before reorganizing, check for completed items:

Move completed items to done.md

Scan for items marked [x]:

1. Create/update .claude/todos/done.md
2. Move completed items under dated section (e.g., ## January 2026)
3. Remove [x] checkbox—use plain bullets in done.md
4. Remove from active.md

Archive if too large

If done.md exceeds 50 items or 500 lines:

1. Create .claude/todos/archive/done-{YYYY-MM}.md
2. Move older items (keep last 2 weeks in done.md)
3. Add note: *Older items archived in .claude/todos/archive/done-{date}.md*

done.md structure:

# Completed Work

Archive of completed features. See `.claude/todos/active.md` for active work.

---

## {Month Year}

### {Category}
- Description of what was done

---

*Older items archived in .claude/todos/archive/done-2025-12.md*

2. Find Project Goals

Search in order:

1. CLAUDE.md — "Goals", "Product Vision", "Objectives" sections
2. .claude/todos/active.md — Goals section at top

If no goals found:

• Tell user: "I couldn't find documented project goals. Before prioritizing, let's define what success looks like."
• Establish 3-5 high-level goals
• Record in active.md Goals section
• Then proceed

3. Summarize

Brief conversational summary:

• How many items captured
• Themes or clusters noticed
• Related items that could combine
• Items complex enough for a spec document

4. Prioritize Against Goals

Evaluate each todo:

• 🎯 Active — Work on RIGHT NOW (1-3 max)
• 📋 Next — Ready to start when Active is done
• 💡 Backlog — Lower priority, needs scoping
• ⚠️ Not Recommended — Decided against (include rationale)

For complex features, suggest creating .claude/docs/feature-{name}.md spec.

5. Rewrite active.md

Replace raw items with organized structure:

# TODO

## Goals

- <goal 1>
- <goal 2>
- <goal 3>

---

## 🎯 Active

*Currently in progress. Limit to 1-3 items.*

- [ ] <highest priority item>

---

## 📋 Next

*Researched, scoped, ready to start.*

### {Category if helpful}
- [ ] <item>

---

## 💡 Backlog

*Ideas and lower priority items.*

### {Category}
- [ ] <item>

### {Complex Feature}
**Spec:** `.claude/docs/feature-{name}.md`
- Brief description

---

## 📚 Specs & Reference

| Document | Description |
|----------|-------------|
| `.claude/docs/feature-x.md` | Spec for feature X |

---

## ⚠️ Not Recommended

### {Rejected idea}
<Brief rationale>

---

*Completed work archived in `.claude/todos/done.md`*

Adapt as needed:

• Skip empty sections
• Items needing >3 lines → spec document
• Keep under ~100 lines of active content

6. Confirm

After rewriting:

• Items per priority tier
• Items moved to done.md
• Specs to create for complex features
• Ask if prioritization makes sense

Principles

1. active.md is for WHAT — Scannable, action-oriented
2. Specs are for HOW — .claude/docs/ for detailed plans
3. done.md is for history — Archive, don't delete
4. Link, don't embed — Reference specs
5. Keep under 100 lines — Move to spec or done.md if long