Instructions

Core Objective

When the user requests to scan a repository for TODOs and update documentation, you must:

1. Authenticate with GitHub.
2. Find all relevant source files in the specified branch.
3. Extract all TODO/FIXME comments.
4. Compare with the existing TODO list in the documentation.
5. Update the documentation by removing completed items and adding new ones, maintaining the specified format and order.

Step-by-Step Process

1. Clarify & Parse User Request

• Identify Target Repository: Extract the repo name and owner from the user's request. If the owner is "my" or "our", you will need to discover the authenticated user's repositories.
• Identify Target Branch: Extract the branch name (e.g., dev, main). Default to main if unspecified.
• Identify Target Documentation File: Usually README.md. Confirm with the user if ambiguous.
• Identify File Types: The request typically specifies file extensions (e.g., .py). Use these. If unspecified, default to common source files (.py, .js, .ts, .java, .cpp, .go).
• Identify Section Title: The request often specifies a section title to update (e.g., ### 📝 Complete TODO List). You MUST keep this exact title unchanged.

2. Authenticate and Discover Repository

• Check for a GitHub token, typically in a file like .github_token in the workspace.
• Use the token to call the GitHub API (github-get_me, github-search_repositories, or direct API calls via local-python-execute with requests).
• If the repository owner is ambiguous (e.g., "my repo"), list the authenticated user's repositories to find the correct one.

3. Fetch Repository Structure & Target Files

• Get the recursive file tree for the target branch using the GitHub API.
• Filter the tree to identify:
  • All source files matching the specified extensions.
  • The target documentation file (e.g., README.md).
• Fetch and save the current content of the documentation file. Note its sha for later updates.

4. Extract TODO Comments from Source Code

• For each identified source file, fetch its content via the GitHub API.
• Use a regular expression (e.g., r'#\\s*TODO[:\\s]*(.*)', case-insensitive) to scan each line for TODO comments.
• For each match, record:
  • file: The repository-relative file path.
  • line: The line number.
  • text: The TODO description (trimmed).
• Save this list as a JSON file in the workspace for later comparison. Sort the list lexicographically by file path, then by line number within the same file.

5. Parse the Existing TODO List from Documentation

• Locate the target section in the documentation using the specified title (e.g., ### 📝 Complete TODO List).
• Parse each TODO item. They are typically in the format: - [ ] **<file_path>:<line_number>** - <description>
• Create a mapping keyed by "<file_path>:<line_number>" for easy comparison.

6. Generate the Updated TODO List

• Identify Completed TODOs: Items present in the documentation mapping but not in the newly extracted code list. These should be removed.
• Identify New TODOs: Items present in the new code list but not in the documentation mapping. These should be added.
• Generate the new, complete TODO list section content:
  1. Start with the exact, original section title.
  2. For each item in the sorted extracted code list, add a line in the format: - [ ] **<file>:<line>** - <text>

7. Update the Documentation File

• In the documentation content, replace the entire old TODO section (from the title to the beginning of the next major section or end of file) with the newly generated content.
• Use the GitHub API to update the file. You must provide:
  • The commit message describing the update.
  • The new file content (base64 encoded).
  • The original file sha.
  • The target branch.
• Verify the update was successful by fetching the file again and checking the TODO count.

8. Provide a Summary

• Report back to the user with a clear summary:
  • Number of TODOs removed (completed).
  • Number of new TODOs added.
  • Final total count.
  • Confirmation that the section title was preserved.
  • The commit SHA of the update.

Key Rules & Constraints

• Order is Mandatory: The final TODO list must be sorted lexicographically by file path, then by ascending line number within each file.
• Preserve the Title: The specified section title string must remain exactly as provided by the user.
• Handle Authentication Errors: If the initial GitHub tool calls fail due to repository access restrictions, fall back to using the token with direct API calls via local-python-execute.
• Rate Limiting: Be mindful of GitHub API rate limits. Introduce small delays (time.sleep) when fetching many files in a loop.
• Error Handling: Check HTTP status codes and provide informative error messages if file fetching or updates fail.