github-todo-issue-creator

name

github-todo-issue-creator

description

Scan codebase for TODO comments and automatically create GitHub issues for each TODO with title, description, assignee, labels, and project assignment. Use when user requests to convert TODOs to issues, track pending work, or create issues from code comments. Triggers when user mentions "create issues from TODOs", "scan TODOs", "convert TODO comments", or wants to track all pending work items in the repository.

GitHub TODO Issue Creator

Overview

This skill automatically scans the codebase for TODO, FIXME, HACK, and other code comments, then creates structured GitHub issues for each item with proper metadata including title, description, assignee, labels, and project assignment. It helps teams track technical debt and pending work items systematically.

When to Use This Skill

Use this skill when:

• Converting TODO comments in code to tracked issues
• Creating a backlog from existing code comments
• Auditing technical debt and pending work
• Onboarding new team members by showing pending tasks
• Preparing sprint planning with existing TODOs
• Linking code comments to GitHub issues for traceability

Trigger Phrases

• "Create issues from all TODOs in the project"
• "Scan for TODO comments and create issues"
• "Convert TODOs to GitHub issues"
• "Create issues from pending work items"
• "Track all TODO comments as issues"
• "Find TODOs and add them to the project board"

Core Workflow

Step 1: Scan for TODO Comments

Search the codebase for TODO-style comments using pattern matching:

Standard TODO Patterns:

// TODO: Add validation for empty customer name
// FIXME: Invoice calculation incorrect with multiple tax rates
// HACK: Temporary workaround - needs proper solution
// BUG: This fails when quantity is zero
// NOTE: Consider refactoring this logic
// XXX: Critical issue - handle edge case

Enhanced TODO Format (with metadata):

// TODO(@username): Add email validation [priority:high] [size:S] [label:enhancement]
// FIXME(@johndoe): Fix calculation [priority:critical] [size:M] [project:Sprint 5]
// TODO: Implement export to Excel [assignee:copilot] [label:feature,api]

Multi-line TODOs:

// TODO: Implement customer merge functionality
//       - Merge customer records
//       - Update related transactions
//       - Archive duplicate entries
//       [priority:medium] [size:L]

Search Strategy:

1. Use grep_search with regex pattern:

(TODO|FIXME|HACK|BUG|XXX|NOTE):\s*(.+)

2. Scan relevant file types:

   • AL files: **/*.al
   • Documentation: **/*.md
   • Configuration: **/*.json, **/*.xml
   • Scripts: **/*.ps1, **/*.sh

3. Exclude certain directories:

   • .git/, .vscode/, node_modules/
   • Build outputs, temp folders

Step 2: Parse TODO Metadata

Extract information from each TODO comment:

Required Information:

• Type: TODO, FIXME, HACK, BUG, etc.
• Description: The TODO text content
• File location: File path and line number

Optional Metadata (from comment or defaults):

• Assignee: @username or [assignee:username]
• Priority: [priority:low|medium|high|critical]
• Size: [size:XS|S|M|L|XL]
• Labels: [label:bug,enhancement] or [labels:feature,api]
• Project: [project:Project Name] or [milestone:v1.2]

Parsing Logic:

interface TodoItem {
  type: 'TODO' | 'FIXME' | 'HACK' | 'BUG' | 'XXX' | 'NOTE';
  description: string;
  filePath: string;
  lineNumber: number;
  assignee?: string;
  priority?: 'low' | 'medium' | 'high' | 'critical';
  size?: 'XS' | 'S' | 'M' | 'L' | 'XL';
  labels?: string[];
  project?: string;
  milestone?: string;
  multiline?: string[]; // Additional description lines
}

Example Parsing:

Input: // TODO(@alice): Add customer validation [priority:high] [size:S] [label:enhancement,validation]

Output:
{
  type: 'TODO',
  description: 'Add customer validation',
  filePath: 'src/Codeunit/CustomerMgmt.Codeunit.al',
  lineNumber: 142,
  assignee: 'alice',
  priority: 'high',
  size: 'S',
  labels: ['enhancement', 'validation']
}

Step 3: Determine Issue Metadata

Apply intelligent defaults when metadata is not specified:

Priority Assignment (based on TODO type):

TODO Type	Default Priority	Rationale
BUG	high	Bugs should be addressed quickly
FIXME	high	Indicates broken functionality
XXX	critical	Usually marks critical issues
HACK	medium	Temporary solutions need proper fix
TODO	medium	Standard work items
NOTE	low	Informational, lower urgency

Size Estimation (based on description keywords):

Keywords	Estimated Size
"fix", "update", "typo", "rename"	XS
"add validation", "improve", "refactor small"	S
"implement", "create", "build"	M
"redesign", "migrate", "integrate"	L
"architecture", "major refactor", "new module"	XL

Label Assignment (based on context):

Context	Labels
File in /Table/	table, database
File in /Page/	page, ui
File in /Codeunit/	codeunit, logic
File in /Report/	report, output
TODO type BUG or FIXME	bug
TODO type HACK	technical-debt
Contains "test", "testing"	testing
Contains "performance", "slow"	performance
Contains "security", "validation"	security
Contains "API", "web service"	api, integration

Assignee Logic:

• If @username in comment → assign to that user
• If [assignee:username] → assign to that user
• If [assignee:copilot] → mark for Copilot agent
• Otherwise → leave unassigned (team to triage)

Project Assignment:

• If [project:Name] → assign to that project
• If [milestone:vX.Y] → assign to that milestone
• Default: No project (can be organized later)

Step 4: Structure Issue Content

Format each TODO as a well-structured GitHub issue:

Issue Title Format:

[TODO-Type] Description (File:Line)

Examples:

• [TODO] Add customer validation (CustomerMgmt.Codeunit.al:142)
• [FIXME] Fix invoice calculation (SalesInvoice.Codeunit.al:89)
• [BUG] Handle zero quantity edge case (ItemJournal.Page.al:234)

Issue Body Template:

## TODO Details

**Type:** [TODO/FIXME/HACK/BUG/etc.]  
**Priority:** [Priority level]  
**Size Estimate:** [Size]

## Description
[Full TODO description including multi-line content]

## Location
**File:** [File path](file-link)  
**Line:** [Line number]

## Context
```al
[Code snippet showing the TODO comment and surrounding context - 5 lines before/after]

Related Code

• File: [File path]
• Function/Object: [Containing function or object name if identifiable]
• Module: [Module/feature area]

Acceptance Criteria

• Address the TODO comment
• Update or remove the TODO comment
• Add tests if applicable
• Update documentation if needed

Additional Notes

[Any additional context from multi-line comments or related TODOs]

---

This issue was automatically created from a TODO comment in the codebase.
Original TODO: Line [line number] in [file path]

### Step 5: Create GitHub Issues

Batch create issues using available tools:

**Method 1: VS Code GitHub Extension**

Open new issue editors and populate them programmatically:

```typescript
for (const todo of todoItems) {
  // Create issue with proper title and body
  const issueTitle = `[${todo.type}] ${todo.description}`;
  const issueBody = formatIssueBody(todo);
  const labels = determineLabels(todo);
  
  // Populate issue via file edit
  // User can review and submit
}

Method 2: GitHub CLI (if available)

gh issue create `
  --title "[TODO] Add customer validation" `
  --body "$issueBody" `
  --label "todo,enhancement,priority: high,size: S" `
  --assignee "alice" `
  --project "Backlog"

Method 3: GitKraken MCP Tools

// Not directly supported for issue creation
// Fall back to CLI or VS Code methods

Batch Creation Strategy:

1. Group related TODOs - Combine TODOs in same file/function if they're related
2. Prioritize creation - Create high-priority issues first
3. Rate limiting - Respect GitHub API limits (batch of 10-20 at a time)
4. Review option - Allow user to review before submitting all
5. Dry-run mode - Generate issue previews without creating

Step 6: Link TODOs to Issues

After creating issues, optionally update TODO comments with issue references:

Before:

// TODO: Add validation for empty customer name

After:

// TODO: Add validation for empty customer name
// Issue: #42 https://github.com/user/repo/issues/42

Or replace with issue reference:

// See Issue #42: Add validation for empty customer name

Update Strategy:

1. Ask user preference: Update comments or leave as-is
2. If updating, use replace_string_in_file to add issue references
3. Maintain traceability between code and issues
4. Optional: Remove TODO comment if issue is created (controversial - some teams prefer keeping it)

Step 7: Generate Summary Report

Provide comprehensive summary of created issues:

Report Format:

## TODO Scan Results

**Repository:** fernandoartalf/Agent_Skill_Demo
**Scan Date:** 2026-01-23
**Files Scanned:** 45
**TODOs Found:** 23
**Issues Created:** 23

### Created Issues

#### High Priority (5)
- #42: [TODO] Add customer validation (CustomerMgmt.Codeunit.al:142)
- #43: [FIXME] Fix invoice calculation (SalesInvoice.Codeunit.al:89)
- #44: [BUG] Handle zero quantity (ItemJournal.Page.al:234)
- #45: [TODO] Implement email validation (ContactMgmt.Codeunit.al:67)
- #46: [FIXME] Currency rounding error (PaymentMgmt.Codeunit.al:156)

#### Medium Priority (12)
- #47: [TODO] Refactor order processing (OrderMgmt.Codeunit.al:78)
- #48: [HACK] Temporary fix for date format (DateUtils.Codeunit.al:45)
[...more issues...]

#### Low Priority (6)
- #59: [NOTE] Consider caching strategy (APIHandler.Codeunit.al:234)
[...more issues...]

### Statistics by Type
- TODO: 15 issues
- FIXME: 5 issues
- BUG: 2 issues
- HACK: 1 issue

### Statistics by File Type
- Codeunits: 12 issues
- Pages: 6 issues
- Tables: 3 issues
- Reports: 2 issues

### Statistics by Size
- XS: 3 issues
- S: 8 issues
- M: 9 issues
- L: 2 issues
- XL: 1 issue

### Project Links
- View all issues: https://github.com/fernandoartalf/Agent_Skill_Demo/issues?q=label:todo
- Project board: [Link if issues added to project]

Advanced Features

Duplicate Detection

Before creating issues, check for existing issues:

1. Check issue title - Look for similar existing issues
2. Check issue body - Search for file path and line number references
3. Ask user - "Issue similar to TODO already exists (#X). Create anyway?"
4. Link instead of create - Update TODO comment with existing issue reference

Smart Grouping

Combine related TODOs into single issues:

Example:

// File: CustomerMgmt.Codeunit.al

// TODO: Add email validation (line 45)
// TODO: Add phone validation (line 67)
// TODO: Add address validation (line 89)

Creates single issue:

Title: [TODO] Add validation to customer management
Description: Multiple validation TODOs found in CustomerMgmt.Codeunit.al:
- Email validation (line 45)
- Phone validation (line 67)
- Address validation (line 89)

TODO Comment Standards

Create a configuration file to define project TODO standards:

.github/todo-config.json:

{
  "patterns": ["TODO", "FIXME", "HACK", "BUG", "XXX"],
  "requireMetadata": false,
  "defaultPriority": "medium",
  "defaultSize": "M",
  "autoAssign": {
    "FIXME": "high",
    "BUG": "critical"
  },
  "labelMapping": {
    "src/Codeunit/": ["codeunit", "logic"],
    "src/Page/": ["page", "ui"],
    "src/Table/": ["table", "database"]
  },
  "excludePatterns": [
    "**/test/**",
    "**/*.md",
    ".vscode/**"
  ],
  "projectMapping": {
    "high": "Current Sprint",
    "medium": "Backlog",
    "low": "Future"
  }
}

Interactive Mode

Allow user to review and customize before creating:

1. Scan and preview - Show all TODOs found
2. User selects - Which TODOs to convert to issues
3. Edit metadata - Adjust priority, size, assignee
4. Batch create - Create selected issues
5. Update comments - Optionally update TODO comments

CI/CD Integration

Create a GitHub Action to run TODO scan on pull requests:

.github/workflows/todo-check.yml:

name: TODO Check
on: [pull_request]
jobs:
  scan-todos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Scan for new TODOs
        run: |
          # Script to find TODOs added in this PR
          # Comment on PR if new TODOs found
          # Optionally require issue reference for TODOs

TODO Tracking Dashboard

Generate a markdown dashboard of all TODOs:

TODO-DASHBOARD.md:

# TODO Tracking Dashboard

Last updated: 2026-01-23

## Summary
- Total TODOs: 23
- Tracked Issues: 23
- Untracked: 0

## By Priority
| Priority | Count | Issues |
|----------|-------|--------|
| Critical | 2 | #44, #46 |
| High | 5 | #42, #43, #45, ... |
| Medium | 12 | #47, #48, ... |
| Low | 4 | #59, ... |

## By Module
| Module | Count | Files |
|--------|-------|-------|
| Customer Management | 5 | CustomerMgmt.Codeunit.al, ... |
| Sales Processing | 8 | SalesInvoice.Codeunit.al, ... |
| Inventory | 4 | ItemJournal.Page.al, ... |

## Recent TODOs (Last 7 days)
- [TODO] Implement export (#42) - Added: 2026-01-22
- [FIXME] Fix calculation (#43) - Added: 2026-01-21

Best Practices

Writing Good TODOs

Good TODO Comments:

// TODO(@alice): Add validation for negative quantities [priority:high] [size:S]
// FIXME: Invoice total calculation fails with multiple tax rates - needs investigation
// HACK: Temporary workaround for date parsing - replace with proper DateTime handling [size:M]

Poor TODO Comments:

// TODO: fix this
// TODO: stuff
// // commented out - doesn't work

Guidelines:

1. Be specific - Clearly describe what needs to be done
2. Add context - Explain why it's needed
3. Include metadata - Priority, size, assignee when known
4. Reference issues - Link to related issues if they exist
5. Keep updated - Remove or update TODOs when work is done

TODO Lifecycle Management

1. Creation - Developer adds TODO during coding
2. Discovery - Automated scan finds the TODO
3. Issue Creation - TODO converted to tracked issue
4. Implementation - Developer works on the issue
5. Verification - Code review checks TODO is addressed
6. Cleanup - TODO comment removed or updated with issue reference

Integration with Development Workflow

During Feature Development:

procedure ProcessOrder()
begin
    // Implementation of basic flow
    
    // TODO(@bob): Add error handling for network failures [priority:high] [size:M]
    // TODO(@bob): Implement retry logic [priority:medium] [size:S]
end;

Before Pull Request:

• Run TODO scan
• Create issues for new TODOs
• Reference issues in PR description
• Decide: address now or track for later

Code Review:

• Review new TODOs in PR
• Ensure TODOs have corresponding issues
• Verify TODO necessity and clarity

Error Handling

Common Issues and Solutions

Issue: Too many TODOs found

• Solution: Filter by priority, date added, or file pattern
• Ask user: "Found 150 TODOs. Filter by priority or create sample?"

Issue: GitHub rate limiting

• Solution: Batch creation in groups of 10
• Add delays between batches
• Offer to create issues in multiple sessions

Issue: Assignee doesn't exist

• Solution: Validate usernames against repository collaborators
• Warn user and leave unassigned or assign to default

Issue: Labels don't exist

• Solution: Check existing labels, create missing ones
• Ask user: "Labels 'todo', 'technical-debt' don't exist. Create them?"

Issue: Project doesn't exist

• Solution: List available projects, ask user to select
• Skip project assignment if not found

Issue: Duplicate TODO comments

• Solution: Detect similar TODOs, ask user to group them
• Create single issue with multiple references

Examples

Example 1: Basic TODO Scan

User: "Scan the project for TODOs and create issues"

Agent Actions:
1. Searches codebase for TODO patterns
2. Finds 15 TODOs across 8 files
3. Parses each TODO, extracts metadata
4. Groups by priority: 3 high, 8 medium, 4 low
5. Creates 15 GitHub issues with proper labels
6. Generates summary report
7. Asks: "Update TODO comments with issue references?"

Example 2: Filtered Scan

User: "Create issues from high-priority TODOs only"

Agent Actions:
1. Scans for TODO/FIXME/BUG patterns
2. Filters to only [priority:high] or FIXME/BUG types
3. Finds 5 high-priority TODOs
4. Creates 5 issues with priority: high label
5. Assigns to specified users or leaves for triage

Example 3: Single File Scan

User: "Create issues from TODOs in CustomerMgmt.Codeunit.al"

Agent Actions:
1. Scans specified file only
2. Finds 3 TODOs
3. Creates 3 issues with file context
4. Labels with "codeunit", "customer-management"
5. Updates TODO comments with issue references

Example 4: Interactive Review

User: "Scan TODOs and let me review before creating issues"

Agent Actions:
1. Scans and finds 20 TODOs
2. Displays list with preview:
   ☐ [TODO] Add validation (line 45) - High, Size S
   ☐ [FIXME] Fix calc (line 89) - High, Size M
   ☑ [TODO] Refactor (line 120) - Medium, Size L (Selected by default)
   [... more TODOs ...]
3. User selects which to create
4. User adjusts metadata if needed
5. Creates selected issues

Configuration

Skill Configuration File

Create .github/skills/github-todo-issue-creator/config.json:

{
  "enabled": true,
  "scanPatterns": ["TODO", "FIXME", "HACK", "BUG", "XXX"],
  "fileExtensions": [".al", ".md", ".json", ".xml"],
  "excludePaths": [".git", ".vscode", "node_modules", ".alpackages"],
  "defaultPriority": "medium",
  "defaultSize": "M",
  "autoUpdate": false,
  "batchSize": 10,
  "requireReview": false,
  "labelPrefix": "todo",
  "issuePrefix": "[TODO]",
  "linkTODOsToIssues": true
}

Success Criteria

A successful TODO scan and issue creation includes: ✅ All TODOs in scope discovered and parsed ✅ Issues created with proper titles and descriptions ✅ Metadata (priority, size, labels) correctly assigned ✅ Code context included in issue body ✅ File locations and line numbers referenced ✅ Issues assigned to correct users or projects ✅ Summary report generated ✅ TODO comments optionally updated with issue references ✅ No duplicate issues created

Required Tools

• grep_search - Search for TODO patterns in codebase
• read_file - Read files to get code context around TODOs
• replace_string_in_file - Update TODO comments with issue references
• run_in_terminal - Use GitHub CLI for issue creation (if available)
• github-pull-request_* - Use GitHub extension tools
• semantic_search - Find related code or documentation

Skill Activation

This skill activates when the user's request includes:

• Words: "scan TODO", "convert TODO", "create issues from TODO", "find TODO"
• Phrases: "create issues from comments", "track pending work", "TODO to issues"
• Context: Working in a repository with code files containing TODO comments
• Intent: Converting technical debt or pending work into tracked items

---

This skill bridges the gap between inline code comments and project management, ensuring no TODO is forgotten and all technical debt is tracked systematically.