Skip to main content

​
Overview

The add-todo command captures ideas, tasks, or issues that surface during work as structured todos for later action. It extracts context from the conversation, organizes by area, and tracks in STATE.md.

​
Syntax

/gsd:add-todo [description]
​
description
string
Brief description of the todo. If omitted, GSD extracts context from the recent conversation.

​
How It Works

  1. Extracts content from arguments or recent conversation
  2. Infers area from file paths or content (api, auth, frontend, etc.)
  3. Checks for duplicates to prevent redundant todos
  4. Creates todo file with frontmatter and structured sections
  5. Updates STATE.md to track pending todo
  6. Commits to git with descriptive message

​
Todo File Structure

---
area: auth
priority: medium
related_files:
  - src/auth/middleware.ts
  - src/auth/tokens.ts
added: 2026-03-06
---

# Add refresh token rotation

## Context
Current implementation uses long-lived refresh tokens.
Security best practice is to rotate on each use.

## Proposed Action
- Implement rotation in token refresh endpoint
- Update token storage schema
- Add expiration tracking

## Related Discussions
- Phase 3: Authentication system
- CONTEXT.md: Security requirements

​
Usage Examples

​
Explicit description

/gsd:add-todo Add rate limiting to API endpoints
GSD creates: 
.planning/todos/api/add-rate-limiting.md

​
From conversation context

During a phase execution: 
You: I noticed the database queries are slow
Assistant: Yes, missing indexes on user_events table
You: We should fix that
/gsd:add-todo
GSD extracts:
  • Description: “Add indexes to user_events table”
  • Area: database
  • Related files: src/db/schema.ts
  • Context: Slow queries, missing indexes

​
During code review

You: This error handling could be better
Assistant: True, it swallows errors silently
/gsd:add-todo Improve error handling in payment processing
GSD creates: 
.planning/todos/payments/improve-error-handling.md

​
From debug session

/gsd:debug Users report intermittent logout
[After investigation]
Assistant: Root cause is session timeout misconfiguration
You: Let's fix that properly later
/gsd:add-todo
GSD extracts from debug context:
  • Description: “Fix session timeout configuration”
  • Area: auth
  • Related: .planning/debug/intermittent-logout.md
  • Context: Debug session findings

​
Area Inference

GSD infers todo area from:
  1. File paths mentioned (e.g., src/auth/* → auth)
  2. Content keywords (e.g., “database query” → database)
  3. Active phase (e.g., working in API phase → api)
  4. User specification (e.g., “frontend todo: …”)
Common areas:
  • api - API endpoints and handlers
  • auth - Authentication and authorization
  • database - Schema, queries, migrations
  • frontend - UI components and pages
  • backend - Server-side logic
  • infra - Infrastructure and deployment
  • testing - Test coverage and quality
  • docs - Documentation
  • general - Miscellaneous or cross-cutting

​
Duplicate Detection

Before creating a todo, GSD checks for similar existing todos: 
/gsd:add-todo Add API caching
GSD finds similar: 
Found similar todo:
- .planning/todos/api/implement-caching.md
  "Implement Redis caching for API responses"

This looks related. Options:
1. Add anyway (different scope)
2. Skip (duplicate)
3. Update existing todo

​
Directory Structure

.planning/
└── todos/
    ├── api/
    │   ├── add-rate-limiting.md
    │   └── implement-caching.md
    ├── auth/
    │   ├── refresh-token-rotation.md
    │   └── fix-session-timeout.md
    ├── database/
    │   └── add-user-events-indexes.md
    └── general/
        └── improve-error-messages.md

​
STATE.md Tracking

Todos are counted in STATE.md: 
## Pending Todos

**By Area:**
- api: 2 todos
- auth: 2 todos
- database: 1 todo
- general: 1 todo

**Total:** 6 pending todos

Use `/gsd:check-todos` to review and work on them.

​
Priority Levels

Todos can have priority indicators: 
---
area: security
priority: high  # high, medium, low
---
High priority:
  • Security vulnerabilities
  • Production bugs
  • Blocking issues
Medium priority:
  • Performance improvements
  • Feature enhancements
  • Refactoring
Low priority:
  • Nice-to-haves
  • Documentation
  • Minor cleanup

​
When to Use

Perfect for

  • Ideas during development
  • Issues found in code review
  • “TODO” comments in code
  • Future improvements
  • Technical debt items
  • Follow-up from debug sessions
  • User feedback items
  • Performance optimizations

Not for

  • Urgent issues (use /gsd:debug or /gsd:quick)
  • Planned roadmap items (use /gsd:plan-phase)
  • Active work (continue current phase)

​
Working on Todos

After capturing todos, work on them: 
# List all todos
/gsd:check-todos

# Filter by area
/gsd:check-todos api

# Select and work on a todo
# GSD offers: quick fix, add to phase, plan new phase

​
Git Commits

Todo creation generates clean commits: 
chore: add todo for API rate limiting

Area: api
File: .planning/todos/api/add-rate-limiting.md

​
Success Criteria

  • ✅ Directory structure created
  • ✅ Existing areas checked
  • ✅ Content extracted (arguments or conversation)
  • ✅ Area inferred correctly
  • ✅ Duplicates checked
  • ✅ File created with slug
  • ✅ STATE.md updated
  • ✅ Git commit created