msd-core/commands/gsd/check-todos.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
gsd:check-todos	List pending todos and select one to work on	area filter	Read Write Bash Glob AskUserQuestion

List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.

Enables reviewing captured ideas and deciding what to work on next.

@.planning/STATE.md @.planning/ROADMAP.md ```bash TODO_COUNT=$(ls .planning/todos/pending/*.md 2>/dev/null | wc -l | tr -d ' ') echo "Pending todos: $TODO_COUNT" ```

If count is 0:

No pending todos.

Todos are captured during work sessions with /gsd:add-todo.

---

Would you like to:

1. Continue with current phase (/gsd:progress)
2. Add a todo now (/gsd:add-todo)

Exit.

Check for area filter in arguments: - `/gsd:check-todos` → show all - `/gsd:check-todos api` → filter to area:api only ```bash for file in .planning/todos/pending/*.md; do created=$(grep "^created:" "$file" | cut -d' ' -f2) title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs) area=$(grep "^area:" "$file" | cut -d' ' -f2) echo "$created|$title|$area|$file" done | sort ```

Apply area filter if specified. Display as numbered list:

Pending Todos:

1. Add auth token refresh (api, 2d ago)
2. Fix modal z-index issue (ui, 1d ago)
3. Refactor database connection pool (database, 5h ago)

---

Reply with a number to view details, or:
- `/gsd:check-todos [area]` to filter by area
- `q` to exit

Format age as relative time.

Wait for user to reply with a number.

If valid: load selected todo, proceed. If invalid: "Invalid selection. Reply with a number (1-[N]) or q to exit."

Read the todo file completely. Display:

## [title]

**Area:** [area]
**Created:** [date] ([relative time] ago)
**Files:** [list or "None"]

### Problem
[problem section content]

### Solution
[solution section content]

If files field has entries, read and briefly summarize each.

```bash ls .planning/ROADMAP.md 2>/dev/null && echo "Roadmap exists" ```

If roadmap exists:

1. Check if todo's area matches an upcoming phase
2. Check if todo's files overlap with a phase's scope
3. Note any match for action options

**If todo maps to a roadmap phase:**

Use AskUserQuestion:

• header: "Action"
• question: "This todo relates to Phase [N]: [name]. What would you like to do?"
• options:
  • "Work on it now" — move to done, start working
  • "Add to phase plan" — include when planning Phase [N]
  • "Brainstorm approach" — think through before deciding
  • "Put it back" — return to list

If no roadmap match:

Use AskUserQuestion:

• header: "Action"
• question: "What would you like to do with this todo?"
• options:
  • "Work on it now" — move to done, start working
  • "Create a phase" — /gsd:add-phase with this scope
  • "Brainstorm approach" — think through before deciding
  • "Put it back" — return to list

**Work on it now:** ```bash mv ".planning/todos/pending/[filename]" ".planning/todos/done/" ``` Update STATE.md todo count. Present problem/solution context. Begin work or ask how to proceed.

Add to phase plan: Note todo reference in phase planning notes. Keep in pending. Return to list or exit.

Create a phase: Display: /gsd:add-phase [description from todo] Keep in pending. User runs command in fresh context.

Brainstorm approach: Keep in pending. Start discussion about problem and approaches.

Put it back: Return to list_todos step.

After any action that changes todo count:

ls .planning/todos/pending/*.md 2>/dev/null | wc -l

Update STATE.md "### Pending Todos" section if exists.

If todo was moved to done/, commit the change:

Check planning config:

COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

If COMMIT_PLANNING_DOCS=false: Skip git operations, log "Todo moved (not committed - commit_docs: false)"

If COMMIT_PLANNING_DOCS=true (default):

git add .planning/todos/done/[filename]
git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true
[ -f .planning/STATE.md ] && git add .planning/STATE.md
git commit -m "$(cat <<'EOF'
docs: start work on todo - [title]

Moved to done/, beginning implementation.
EOF
)"

Confirm: "Committed: docs: start work on todo - [title]"

- Moved todo to `.planning/todos/done/` (if "Work on it now") - Updated `.planning/STATE.md` (if todo count changed)

<anti_patterns>

• Don't delete todos — move to done/ when work begins
• Don't start work without moving to done/ first
• Don't create plans from this command — route to /gsd:plan-phase or /gsd:add-phase </anti_patterns>

<success_criteria>

• All pending todos listed with title, area, age
• Area filter applied if specified
• Selected todo's full context loaded
• Roadmap context checked for phase match
• Appropriate actions offered
• Selected action executed
• STATE.md updated if todo count changed
• Changes committed to git (if todo moved to done/) </success_criteria>