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):

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

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

1. Read entire codebase structure: 400-600 tokens
2. Analyze project conventions: 300-500 tokens
3. Read full file contents: 600-1,000 tokens
4. Manual TODO creation with Edit: 400-600 tokens
5. Re-read for verification: 400-600 tokens
6. 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:

1. Find the exact location where it belongs
2. Analyze surrounding code for context
3. Create clear, actionable TODO comments
4. 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.