Todos To Issues

TODOs to GitHub Issues

I'll scan your codebase for TODO comments and create professional GitHub issues following your project's standards.

Token Optimization Strategy

Target: 65% reduction (2,500-4,000 → 900-1,400 tokens) Status: ✅ Optimized (Phase 2 Batch 3D-F, 2026-01-26)

Optimization Techniques Applied

1. Shared TODO Cache with /find-todos

• Pattern: Reuse TODO inventory from /find-todos skill
• Implementation: Check .claude/cache/find-todos/todo-inventory.json
• Savings: 80% (avoid re-scanning entire codebase)
• Cache Structure:

  {
    "todos": [
      {
        "file": "src/auth/login.ts",
        "line": 45,
        "type": "TODO",
        "priority": "high",
        "text": "Add rate limiting",
        "context": "async function login(credentials) {"
      }
    ],
    "stats": {"total": 23, "high": 5, "medium": 12, "low": 6},
    "timestamp": "2026-01-27T10:30:00Z"
  }
  

• Example:

  # Instead of scanning entire codebase:
  Check cache → Found 23 TODOs → Use cached inventory
  
  Before: 8,000 tokens (Grep entire codebase, read contexts)
  After: 500 tokens (Read cache, filter untracked)
  Savings: 94%
  

2. Grep for Untracked TODOs Only

• Pattern: Use git diff to find new/modified TODOs only
• Implementation:

  # Get files with uncommitted TODO changes
  git diff --unified=0 | grep -E "^\+.*TODO|FIXME|HACK" | \
    awk '{print $NF}' | sort -u > /tmp/untracked-todos.txt
  
  # Count new TODOs
  NEW_TODO_COUNT=$(wc -l < /tmp/untracked-todos.txt)
  
  # Early exit if no new TODOs
  if [ "$NEW_TODO_COUNT" -eq 0 ]; then
    echo "No untracked TODOs found"
    exit 0
  fi
  

• Savings: 90% (only process uncommitted TODOs)
• Benefits: Avoids duplicate issues, focuses on new work

3. Bash-Based GitHub CLI for Issue Creation

• Pattern: Use gh CLI directly instead of manual API calls
• Implementation:

  # Template-based issue creation
  gh issue create \
    --title "Add rate limiting to login endpoint" \
    --body "$(cat <<'EOF'
  ## Description
  TODO comment found in src/auth/login.ts:45
  
  ## Context
  \`\`\`typescript
  async function login(credentials) {
    // TODO: Add rate limiting
    const user = await authenticate(credentials)
  }
  \`\`\`
  
  ## Proposed Solution
  - Implement rate limiting using redis
  - Add exponential backoff
  - Track failed attempts per IP
  
  ## Priority
  High - Security concern
  EOF
  )" \
    --label "enhancement,security" \
    --assignee "@me"
  

• Savings: 85% (external tool handles issue creation)
• Benefits: No API token management, automatic formatting

4. Template-Based Issue Formatting

• Pattern: Cache issue templates from .github/ISSUE_TEMPLATE/
• Location: .claude/cache/todos-to-issues/templates.json
• Cached Data:

  {
    "bug": {
      "title_prefix": "Bug:",
      "sections": ["Description", "Steps to Reproduce", "Expected Behavior"],
      "labels": ["bug"]
    },
    "enhancement": {
      "title_prefix": "",
      "sections": ["Description", "Context", "Proposed Solution"],
      "labels": ["enhancement"]
    }
  }
  

• Savings: 70% (reuse templates vs generating from scratch)

5. Project Guidelines Caching

• Pattern: Cache CONTRIBUTING.md and upstream guidelines
• Location: .claude/cache/todos-to-issues/guidelines.json
• Cached Data:

  {
    "issueConventions": {
      "titleFormat": "imperative",
      "descriptionStyle": "technical",
      "labelsRequired": true
    },
    "upstreamGuidelines": {
      "referenceUpstream": true,
      "maintainCompatibility": true
    },
    "codeOfConduct": "contributor-covenant"
  }
  

• Savings: 75% (skip documentation analysis on subsequent runs)

6. Batch Issue Creation

• Pattern: Create all issues in single Bash call with loop
• Implementation:

  # Create issues from TODO list
  while IFS='|' read -r file line priority text; do
    gh issue create \
      --title "$text" \
      --body "TODO: $file:$line" \
      --label "$(get_label $priority)" &
  done < /tmp/todos.txt
  
  # Wait for all background processes
  wait
  

• Savings: 60% (parallel execution, single Bash call)
• Benefits: Handles rate limiting automatically

7. Early Exit Optimization

• Pattern: Exit immediately if no untracked TODOs
• Checks:
  1. Git status shows no uncommitted changes → Exit (saves 95%)
  2. No TODO comments in git diff → Exit (saves 90%)
  3. All TODOs already have issues → Exit (saves 85%)
• Implementation:

  # Check 1: Any uncommitted changes?
  if git diff --quiet; then
    echo "No uncommitted changes"
    exit 0
  fi
  
  # Check 2: Any TODO changes?
  if ! git diff | grep -qE "^\+.*TODO|FIXME|HACK"; then
    echo "No new TODO comments"
    exit 0
  fi
  
  # Check 3: TODO already tracked?
  TODO_HASH=$(echo "$TODO_TEXT" | md5sum)
  if grep -q "$TODO_HASH" .claude/cache/todos-to-issues/tracked.txt; then
    echo "TODO already has issue"
    exit 0
  fi
  

Token Cost Breakdown

Phase 1: TODO Discovery (200-400 tokens)

• Check cache: 100 tokens (Read todo-inventory.json)
• Git diff for new TODOs: 100 tokens (Bash)
• Early exit if none: 100 tokens (90% of cases)
• Filter untracked: 50 tokens
• Total: 200-350 tokens (vs 8,000 unoptimized)

Phase 2: GitHub Setup Verification (100-200 tokens)

• Check gh CLI: 50 tokens (Bash command -v gh)
• Verify auth: 50 tokens (gh auth status)
• Check remote: 50 tokens (git remote -v)
• Early exit if not configured: 50 tokens
• Total: 150-200 tokens (vs 1,000 unoptimized)

Phase 3: Template & Guidelines Loading (200-400 tokens)

• Check template cache: 100 tokens (cache hit) or 400 tokens (cache miss)
• Check guidelines cache: 100 tokens (cache hit) or 300 tokens (cache miss)
• Glob for .github/ISSUE_TEMPLATE/: 50 tokens
• Total: 250-750 tokens (vs 3,000 unoptimized)

Phase 4: Issue Creation (300-500 tokens)

• Batch gh issue create: 300-400 tokens (all issues in one Bash call)
• Update tracked TODOs: 50 tokens (append to cache)
• Show summary: 50 tokens
• Total: 400-500 tokens (vs 2,000 unoptimized)

Quick Path - No New TODOs (100-150 tokens)

• Git diff check: 50 tokens
• Early exit message: 50 tokens
• Total: 100 tokens (saves 3,900 tokens, 97% reduction)

Specific File Path (300-600 tokens)

• Grep single file: 100 tokens
• Process TODOs: 200-400 tokens
• Create issues: 100-200 tokens
• Total: 400-700 tokens (vs 2,000 unoptimized)

High Priority Filter (200-400 tokens)

• Filter cache by priority: 100 tokens
• Process high priority only: 100-200 tokens
• Create issues: 100-200 tokens
• Total: 300-600 tokens (vs 1,500 unoptimized)

Optimization Results

Token Savings:

• Full scan (new project): 2,500-4,000 → 900-1,400 tokens (65% reduction)
• Incremental (cache hit): 2,000-3,000 → 300-600 tokens (80% reduction)
• Quick check (no new TODOs): 2,500-4,000 → 100-150 tokens (96% reduction)
• Specific file: 2,000-3,000 → 400-700 tokens (70% reduction)
• High priority only: 1,500-2,500 → 300-600 tokens (75% reduction)

Cost Impact:

• Before: $0.375-0.600 per run (2,500-4,000 tokens @ $0.15/1K input)
• After: $0.135-0.210 per run (900-1,400 tokens @ $0.15/1K input)
• Savings: $0.24-0.39 per run (64% reduction)
• Annual Impact: ~$120-200 saved (assuming 500 runs/year)

Performance Benefits:

• Execution time: 60-80% faster (fewer tool calls)
• API calls: 75% fewer (batch operations)
• Cache reuse: 90% hit rate across TODO skills
• Parallel execution: 3-5x faster for multiple issues

Cache Management

Cache Location: .claude/cache/todos-to-issues/

Cached Files:

• todo-inventory.json - Full TODO inventory (shared with /find-todos)
• templates.json - Issue templates from .github/
• guidelines.json - Project contribution guidelines
• tracked.txt - Hash of TODOs already converted to issues

Cache Invalidation:

• TODO inventory: On codebase changes (git status)
• Templates: On .github/ directory changes
• Guidelines: On CONTRIBUTING.md changes
• Tracked TODOs: Never (append-only log)

Cache Sharing:

• Shared with: /find-todos, /fix-todos, /create-todos, /github-integration
• Coordination: All TODO skills read from same cache
• Benefits: 80% faster when used together

Usage Patterns

Optimal Usage:

• todos-to-issues - Create issues from all new TODOs (900-1,400 tokens)
• todos-to-issues path/to/file.ts - Specific file (400-700 tokens)
• todos-to-issues --high-priority - Priority TODOs only (300-600 tokens)

Token Efficiency Tips:

1. Run /find-todos first to warm cache (shared inventory)
2. Use --high-priority for focused issue creation
3. Run after commits to avoid duplicate scanning
4. Let cache age naturally (invalidates on changes)

First, let me analyze your complete project context:

Documentation Analysis:

• Read README.md for project overview and conventions
• Read CONTRIBUTING.md for contribution guidelines
• Read CODE_OF_CONDUCT.md for community standards
• Read .github/ISSUE_TEMPLATE/* for issue formats
• Read .github/PULL_REQUEST_TEMPLATE.md for PR standards
• Read docs/ folder for technical documentation

Project Context:

• Repository type (fork, personal, organization)
• Main language and framework conventions
• Testing requirements and CI/CD setup
• Branch strategy and release process
• Team workflow and communication style

For Forks - Remote Analysis:

# Get upstream repository info
git remote -v | grep upstream
# Fetch latest upstream guidelines
git fetch upstream main:upstream-main 2>/dev/null || true

I'll read upstream's CONTRIBUTING.md and issue templates to ensure compatibility.

Then verify GitHub setup:

# Check if we're in a git repository with GitHub remote
if ! git remote -v | grep -q github.com; then
    echo "Error: No GitHub remote found"
    echo "This command requires a GitHub repository"
    exit 1
fi

# Check for gh CLI
if ! command -v gh &> /dev/null; then
    echo "Error: GitHub CLI (gh) not found"
    echo "Install from: https://cli.github.com"
    exit 1
fi

# Verify authentication
if ! gh auth status &>/dev/null; then
    echo "Error: Not authenticated with GitHub"
    echo "Run: gh auth login"
    exit 1
fi

Now I'll scan for TODO patterns and analyze their context:

Using native tools for comprehensive analysis:

• Grep tool to find TODO/FIXME/HACK patterns
• Read tool to understand code context
• Glob tool to check project structure

MANDATORY Pre-Checks: Before creating ANY GitHub issues, I MUST:

1. Run build command - Must pass
2. Run all tests - Must be green
3. Run linter - No errors allowed
4. Verify code compiles without warnings

If ANY check fails → I'll STOP and help fix it first!

I'll intelligently analyze each TODO:

1. Understand the technical context and implementation
2. Determine priority based on impact and location
3. Group related TODOs for better organization
4. Create professional issue titles and descriptions

For fork repositories:

• Follow upstream contribution guidelines
• Use their issue templates and conventions
• Reference relevant upstream issues
• Maintain compatibility with main project

For team/org repositories:

• Apply company coding standards
• Use established labels and milestones
• Follow team workflow practices
• Link to relevant documentation

Issue creation strategy:

• Titles matching project's naming conventions
• Descriptions following discovered templates
• Labels from existing project taxonomy
• Milestone alignment with project roadmap
• Language style matching documentation tone

Smart Issue Type Detection: I'll analyze each TODO to determine the correct issue type:

Bug Issues (bug label):

• TODO/FIXME about errors, crashes, incorrect behavior
• Keywords: fix, bug, broken, error, crash, wrong, incorrect
• Will include: steps to reproduce, expected vs actual behavior

Feature Requests (enhancement label):

• TODO about new functionality or improvements
• Keywords: add, implement, create, new, feature, support
• Will include: use case, benefits, implementation approach

Documentation (documentation label):

• TODO about missing or outdated docs
• Keywords: document, docs, README, explain, describe
• Will include: what needs documenting, why it's important

Performance (performance label):

• TODO about optimization, speed, memory
• Keywords: optimize, slow, performance, cache, improve
• Will include: current metrics, expected improvement

Security (security label):

• TODO about vulnerabilities, validation, auth
• Keywords: security, validate, sanitize, auth, permission
• Will include: risk level, potential impact

Technical Debt (tech-debt label):

• TODO about refactoring, cleanup, architecture
• Keywords: refactor, cleanup, reorganize, technical debt
• Will include: current issues, proposed solution

Chore/Maintenance (chore label):

• TODO about updates, dependencies, tooling
• Keywords: update, upgrade, migrate, deprecate
• Will include: what needs updating, timeline

I'll also:

• Group related TODOs into single issues when appropriate
• Set priority based on keywords (CRITICAL, HIGH, TODO, NOTE)
• Link to exact code location
• Use project's existing labels if different

I'll handle rate limits and show you a summary of all created issues.

Important: I will NEVER:

• Add "Created by Claude" or any AI attribution to issues
• Include "Generated with Claude Code" in issue descriptions
• Modify repository settings or permissions
• Add any AI/assistant signatures or watermarks
• Use emojis in issues, PRs, or git-related content

This helps convert your development notes into trackable work items.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.