# todo

> Manage TODO.md files for tracking ideas, bugs, and feature requests. Use this when users want to add items to their TODO list using conventional commit format, or when they say "/todo <description>".

- Author: James Felix Black
- Repository: tftio/claude-skills
- Version: 20260130135044
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/tftio/claude-skills
- Web: https://mule.run/skillshub/@@tftio/claude-skills~todo:20260130135044

---

---
name: todo
description: Manage TODO.md files for tracking ideas, bugs, and feature requests. Use this when users want to add items to their TODO list using conventional commit format, or when they say "/todo <description>".
tools: Bash, Read, Edit, Write
metadata:
  version: 1.0.0
  tags: [todo, tracking, conventional-commits]
---

# TODO.md Management

This skill manages TODO.md files for tracking ideas, bugs, and feature requests that haven't yet been formalized into GitHub issues or project tasks.

## Entry Format

Each TODO entry follows this format:

```
- [ ] **type(scope)**: description - @author YYYY-MM-DD HH:MM
```

### Conventional Commit Types

| Type | Description |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting (no code change) |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or correcting tests |
| `build` | Changes to build system or dependencies |
| `ci` | Changes to CI configuration |
| `chore` | Other changes that don't modify src or test files |

## Adding a TODO Item

When the user invokes `/todo <description>`, follow these steps:

### Step 1: Get Metadata

```bash
# Get git user name
git config user.name

# Get current date/time in UTC
date -u "+%Y-%m-%d %H:%M"
```

### Step 2: Parse the Description

The user's description may include an explicit type prefix or not:

**With explicit type:**
- `/todo fix(api): endpoint returns 500 on empty input` -> type=fix, scope=api
- `/todo feat: add dark mode support` -> type=feat, scope=none
- `/todo refactor(auth): simplify token refresh logic` -> type=refactor, scope=auth

**Without explicit type (default to `chore`):**
- `/todo switch ARN from hardcoded to dynamic` -> type=chore, scope=none
- `/todo clean up unused imports` -> type=chore, scope=none

### Step 3: Locate TODO.md

Look for TODO.md in the current working directory. If it doesn't exist, create it with the standard boilerplate:

```markdown
# TODO

A staging area for ideas, bugs, and feature requests discovered during development but not yet formalized into GitHub issues or project tasks.

## Format

Each item uses [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) type prefixes:

| Type | Description |
|------|-------------|
| `feat` | New feature |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, missing semicolons, etc. (no code change) |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or correcting tests |
| `build` | Changes to build system or dependencies |
| `ci` | Changes to CI configuration |
| `chore` | Other changes that don't modify src or test files |

Items include: checkbox, type, optional scope, description, author, and timestamp.

```
- [ ] **type(scope)**: description - @author YYYY-MM-DD HH:MM
```

When an item is addressed (issue created, PR merged, or intentionally declined), check the box and optionally add a reference.

---

## Items

```

### Step 4: Append the Entry

Append the new entry to the end of the TODO.md file:

```
- [ ] **type(scope)**: description - @author YYYY-MM-DD HH:MM
```

If scope is empty, omit the parentheses:

```
- [ ] **type**: description - @author YYYY-MM-DD HH:MM
```

### Step 5: Confirm

Report to the user what was added:

```
Added to TODO.md:
- [ ] **feat(ui)**: add dark mode toggle - @jfb 2026-01-29 23:15
```

## Parsing Rules

### Type Detection

Check if the description starts with a conventional commit type followed by optional scope and colon:

```
^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\([^)]+\))?:\s*(.+)$
```

If matched:
- Group 1 = type
- Group 2 = scope (with parentheses, may be empty)
- Group 3 = description

If not matched:
- type = "chore"
- scope = empty
- description = entire input

### Scope Extraction

If scope is present (e.g., `(api)`), extract just the text without parentheses for the output.

## Examples

**Input:** `/todo feat(auth): add OAuth2 support for GitHub login`
**Output:** `- [ ] **feat(auth)**: add OAuth2 support for GitHub login - @jfb 2026-01-29 23:15`

**Input:** `/todo fix: prevent race condition in cache invalidation`
**Output:** `- [ ] **fix**: prevent race condition in cache invalidation - @jfb 2026-01-29 23:15`

**Input:** `/todo update the README with installation instructions`
**Output:** `- [ ] **chore**: update the README with installation instructions - @jfb 2026-01-29 23:15`

**Input:** `/todo perf(db): add index on user_id column`
**Output:** `- [ ] **perf(db)**: add index on user_id column - @jfb 2026-01-29 23:15`

## Listing TODOs

When asked to show or list TODOs, read and display the contents of TODO.md, optionally filtering by:
- Type (e.g., "show me all fix items")
- Scope (e.g., "what TODOs are there for the API?")
- Status (checked vs unchecked)

## Marking Complete

When asked to complete or check off a TODO:
1. Find the matching unchecked item
2. Change `- [ ]` to `- [x]`
3. Optionally append a reference (e.g., `(#123)` or `(PR #456)`)