Add Todo

---
name: add-todo
description: Add a properly formatted TODO item to TODOS.md. Use when you need to capture a new task, bug, or feature request during development.
allowed-tools: Read, Write, Edit, AskUserQuestion
---

# Add TODO Skill

Add a new TODO item to TODOS.md with proper formatting that integrates with `/list-todos` and `/run-todos`.

## Directory Guard

Before starting, check if `TODOS.md` exists in the current working directory.

- If it exists, read it to understand the current structure
- If it does not exist, create it with the standard template (see below)

## TODO Format Reference

TODOs in this system follow a specific format for compatibility with other skills.
Basic format: `- [ ] **[{Priority} / {Effort}]** {Title} — {Brief description}`

See [references/format-reference.md](references/format-reference.md) for the full format specification including components, tags, status markers, and clarifications sections.

## Workflow

Copy this checklist and track progress:

```
Add TODO Progress:
- [ ] Step 1: Gather information (title, priority, effort, description, section)
- [ ] Step 2: Format the TODO line
- [ ] Step 3: Read current TODOS.md
- [ ] Step 4: Insert TODO into selected section
- [ ] Step 5: Confirm addition
```

### Step 1: Gather Information

Use AskUserQuestion to collect TODO details:

**Question 1: Title**
```
Question: "What is the TODO item? (brief, actionable title)"
Header: "Title"
Options:
  - Label: "Enter title"
    Description: "Type your TODO title"
```

(User will select "Other" and type their title)

**Question 2: Priority**
```
Question: "What priority level?"
Header: "Priority"
Options:
  - Label: "P1 / High (Recommended)"
    Description: "Important feature or fix, do soon"
  - Label: "P0 / Critical"
    Description: "Blocking issue, must do immediately"
  - Label: "P2 / Low"
    Description: "Nice to have, do when time permits"
```

**Question 3: Effort**
```
Question: "Estimated effort?"
Header: "Effort"
Options:
  - Label: "Medium (Recommended)"
    Description: "A few hours to a day of work"
  - Label: "Low"
    Description: "Quick task, under an hour"
  - Label: "High"
    Description: "Multiple days or significant complexity"
```

**Question 4: Description (Optional)**
```
Question: "Add a description? (optional details, context, or requirements)"
Header: "Description"
Options:
  - Label: "Skip description"
    Description: "Title is sufficient"
  - Label: "Add description"
    Description: "Include additional context"
```

If "Add description", prompt for the description text.

**Question 5: Section**
```
Question: "Which section should this go in?"
Header: "Section"
Options:
  - Label: "In Progress (Recommended)"
    Description: "Active TODO items for current work"
  - Label: "Future Concepts"
    Description: "Ideas to explore later"
```

### Step 2: Format the TODO

Construct the TODO line:

```markdown
- [ ] **[{Priority} / {Effort}]** {Title}{if description: — {Description}}
```

**Examples:**

Simple:
```markdown
- [ ] **[P1 / Medium]** Add logout button to navbar
```

With description:
```markdown
- [ ] **[P1 / Medium]** Add logout button to navbar — Should redirect to login page after logout
```

With multiplier (if user specifies):
```markdown
- [ ] **[P1 / Medium x1.5]** Add logout button to navbar — High user demand
```

### Step 3: Read Current TODOS.md

Read TODOS.md to find the appropriate section.

**Section Detection:**
- Look for `## In Progress` heading
- Look for `## Future Concepts` heading
- If neither exists, create the section

### Step 4: Insert TODO

Insert the new TODO at the **end** of the selected section, before the next section heading or end of file.

Use the Edit tool to insert the TODO.

### Step 5: Confirm

Output confirmation:

```
TODO ADDED
==========

Added to: {Section}

{The formatted TODO line}

Next steps:
- Run /list-todos to analyze and prioritize
- Use Q&A to clarify requirements
- Mark [ready] when requirements are clear
- Run /run-todos to implement
```

## TODOS.md Template

If TODOS.md doesn't exist, create it:

```markdown
# TODO

## In Progress

{new TODO here}

## Future Concepts

(Ideas to explore later)
```

## Error Handling

| Situation | Action |
|-----------|--------|
| TODOS.md cannot be written | Check file permissions; report the error and suggest `touch TODOS.md` or check directory permissions |
| Existing TODOS.md has unexpected format | Preserve original content, add the new TODO at the end of the file, warn user about non-standard format |
| User provides ambiguous priority/effort | Default to P2 / Medium and note the default in the confirmation message |
| File is very large (>500 lines) | Warn user that the file is large; suggest archiving completed items to TODOS-ARCHIVE.md |
| Target section heading not found in TODOS.md | Create the missing section heading, then insert the TODO beneath it |

## Notes

- **Preserve existing format** — Match the style of existing TODOs in the file
- **Don't add [ready] automatically** — Let /list-todos Q&A determine readiness
- **Default to In Progress** — Most new TODOs are active work items
- **Keep titles actionable** — Start with a verb (Add, Fix, Update, Implement)
- **Descriptions are optional** — Only add if title alone is ambiguous