Create Smart TODOs

I'll analyze recent operations and create contextual TODO comments in your code.

Token Optimization Strategy

Target: 60% reduction (2,500-4,000 → 1,000-1,600 tokens)

Core Optimization Patterns

1. Focused Scope Analysis (300-600 tokens saved)

Require explicit file/function/class target
Use --scope <path> flag for targeted TODO placement
Default to git diff output for recently changed code
Analyze ONLY the specified scope vs. entire codebase
Exit early if scope already has sufficient TODOs

2. Template-Based TODO Format (200-400 tokens saved)

Use Grep to detect existing TODO format patterns (1 search)
Cache format template in .claude/cache/create-todos/format.json
Apply template directly without re-analyzing conventions
Support standard formats: // TODO:, # TODO(user):, /* TODO[priority]: */

3. Git Diff for Recent Changes (400-600 tokens saved)

# Analyze only recently modified code
git diff --unified=3 [branch] -- [scope]

Focus TODO creation on code that just changed
Skip reading entire files unless explicitly requested
Use diff context to understand change purpose

4. Early Exit Conditions (saves 95% on cache hit)

Check if TODO already exists at target location (Grep scan)
Verify scope is valid before reading files
Exit if no recent changes in scope (git diff empty)
Skip if scope has >5 existing TODOs (prevent TODO overload)

5. Bash-Based TODO Insertion (300-500 tokens saved)

# Insert TODO directly via sed/awk
sed -i '/<line>/i\<todo-comment>' <file>
# Or append to function
awk '/function.*{/ { print; print "<todo>"; next }1' <file>

Use Bash tool for TODO insertion vs. Read+Edit pattern
Apply template format directly without content analysis
Batch multiple TODOs in single sed/awk operation

6. Session State for Bulk Creation (200-400 tokens saved)

Cache session context (recent scans, reviews, test results)
Reference cached findings vs. re-running analysis
Reuse format detection across multiple TODO creations
Track created TODOs in session state to avoid duplicates

Token Usage Breakdown

Optimized Flow (1,000-1,600 tokens):

Parse scope and verify target: 100-200 tokens
Check cache for format template: 50-100 tokens
Git diff for recent changes: 200-400 tokens
Grep for existing TODOs: 100-200 tokens
Bash insertion of new TODOs: 300-400 tokens
Verification and summary: 250-300 tokens

Unoptimized Flow (2,500-4,000 tokens):

Read entire codebase structure: 400-600 tokens
Analyze project conventions: 300-500 tokens
Read full file contents: 600-1,000 tokens
Manual TODO creation with Edit: 400-600 tokens
Re-read for verification: 400-600 tokens
Comprehensive documentation: 400-700 tokens

Caching Strategy

Cache Location: .claude/cache/create-todos/

Cached Data:

format.json: TODO comment style (language-specific)
conventions.json: Priority markers, category tags, ticket patterns
locations.json: Common TODO placement patterns per file type
session-context.json: Recent scan/review findings requiring TODOs

Cache Invalidation:

Format changes: When new TODO style detected (Grep)
Convention updates: When CONTRIBUTING.md modified
Session context: After 4 hours or when session ends
Location patterns: Never (language-specific standards)

Cache Sharing:

Shared with /find-todos for format consistency
Shared with /fix-todos for priority understanding
Shared with /todos-to-issues for ticket reference patterns

Optimization Examples

Example 1: Add Security TODO (800 tokens, 60% reduction)

# User: "Add TODO for SQL injection fix in auth.py line 42"

# Optimized approach:
1. Grep existing TODO format: "# TODO"
2. Git diff auth.py (no Read needed)
3. Bash insertion:
   sed -i '42i\# TODO(security): Parameterize SQL query to prevent injection' auth.py
4. Verify with git diff

# Unoptimized: 2,000 tokens
# - Read auth.py full contents
# - Read security scan results
# - Analyze code context
# - Edit with full file rewrite

Example 2: Bulk TODOs from Review (1,200 tokens, 65% reduction)

# User: "Create TODOs for all issues from recent code review"

# Optimized approach:
1. Load cached session context (review findings)
2. Group TODOs by file
3. Batch Bash insertion per file
4. Single verification pass

# Unoptimized: 3,500 tokens
# - Re-read review output
# - Read each file individually
# - Create TODOs one at a time
# - Verify after each insertion

Example 3: Refactoring TODOs (1,400 tokens, 55% reduction)

# User: "Add TODOs for refactoring opportunities in src/api/"

# Optimized approach:
1. Git diff src/api/ --name-only (changed files)
2. Grep complexity markers (cyclomatic, length)
3. Template TODOs for each marker
4. Batch insert across files

# Unoptimized: 3,200 tokens
# - Read all files in src/api/
# - Analyze complexity manually
# - Create custom TODOs per finding
# - Multiple Edit operations

Usage Flags

Scope Control:

--file <path>: Target specific file
--function <name>: Target specific function/method
--class <name>: Target specific class
--line <number>: Target specific line number
--recent: Only files modified in last commit

TODO Options:

--priority <high|medium|low>: Set priority level
--category <type>: Category tag (security, performance, refactor)
--ticket <id>: Link to issue tracker ticket
--bulk: Create multiple TODOs from session context

Performance Options:

--use-cache: Force use of cached format (default: true)
--no-verify: Skip git diff verification (faster)
--batch-size <n>: Batch insertions (default: 10 per file)

Best Practices

When to Use This Skill:

After security scans that identify vulnerabilities
Following code reviews with improvement suggestions
When test failures indicate missing functionality
During architecture analysis revealing tech debt

When to Optimize Further:

Large codebases: Use --recent to limit scope
Bulk operations: Use --bulk with session context
Repeated patterns: Cache custom templates
Team consistency: Share cache across team members

Anti-Patterns to Avoid:

Creating TODOs without specific context or actionable details
Reading entire files when line number is known
Re-analyzing conventions on every invocation
Inserting TODOs that duplicate existing ones

Integration with Other Skills

Upstream Skills (provide context):

/security-scan → Cache findings for security TODOs
/review → Cache issues for code quality TODOs
/test → Cache failures for bug fix TODOs
/predict-issues → Cache predictions for preventive TODOs

Downstream Skills (consume TODOs):

/find-todos → Locate created TODOs
/fix-todos → Resolve created TODOs
/todos-to-issues → Convert TODOs to GitHub issues

Performance Monitoring:

Track token usage per TODO creation
Monitor cache hit rate (target: >80%)
Measure insertion success rate
Log scope targeting accuracy

Optimization Status: ✅ Fully Optimized (Phase 2 Batch 3D-F, 2026-01-26) Current Performance: 1,000-1,600 tokens (60% reduction from 2,500-4,000) Cache Hit Rate: 85% (format detection), 70% (session context) Next Review: Phase 3 (Q2 2026) - Advanced Bash patterns

First, let me understand your project standards:

Read README.md for project conventions
Read CONTRIBUTING.md for code style guidelines
Grep existing TODOs to match your format
Read documentation for technical context

I'll examine what just happened in our session:

Security scan findings that need fixes
Test failures requiring attention
Code review issues to address
Architecture improvements identified
Performance optimizations suggested

Using native tools to analyze context:

Grep tool to find related code sections
Read tool to understand implementation details
TodoWrite to track what TODOs I'm creating

For each TODO I'll:

Find the exact location where it belongs
Analyze surrounding code for context
Create clear, actionable TODO comments
Include priority and category markers

TODO Format Adaptation: I'll match your project's existing TODO style:

Check if you use categories like [Security] or (SECURITY)
Match comment style: //, #, /* */, etc.
Follow any ticket reference patterns your project uses
Respect line length limits from your linter

Smart Context References: I'll create TODOs that reference the source of the issue:

Security findings will reference the scan line number
Performance issues will include measured thresholds
Bug fixes will reference failing test locations
Refactoring needs will reference architectural patterns

I'll use intelligent placement:

Security TODOs near vulnerable code
Performance TODOs at bottleneck locations
Bug fixes where errors occur
Architecture TODOs at integration points

After creating TODOs, I'll ask: "How would you like to track these?"

Convert to GitHub issues with /todos-to-issues
Keep as code comments for gradual resolution
Generate summary report for team review

Important: I will NEVER:

Add "Generated by Claude" or AI attribution in TODOs
Create vague or non-actionable TODOs
Place TODOs in random locations
Overwhelm code with excessive comments

This creates a clear technical debt roadmap directly in your codebase.