| name | todosaurus-skill |
| description | Connect unresolved TODO markers to GitHub issues and use IgnoreTODO regions for false positives. |
Todosaurus TODO-to-Issue Connector
Use this skill when a repository has unresolved TODO markers and they must be connected to GitHub issues, while allowing IgnoreTODO regions for intentional false positives.
Installation prerequisites
Ensure Todosaurus is installed before running this workflow.
If it's not installed, you can install it globally:
$ dotnet tool install --global FVNever.Todosaurus.Cli
Or install it locally in the repository:
$ dotnet new tool-manifest
(only if .config/dotnet-tools.json is not present yet), then:
$ dotnet tool install FVNever.Todosaurus.Cli
Verify installation:
$ todosaurus --version
$ dotnet tool run todosaurus --version
If installed as a global tool, run it as todosaurus. If installed via a tool manifest, run it as dotnet tool run todosaurus.
Workflow
- Run Todosaurus in the repository root (global install):
$ todosaurus
For local tool-manifest install, use:
$ dotnet tool run todosaurus
- Parse unresolved TODO findings and classify each finding:
- Actionable TODO: a real follow-up task that should be tracked with a GitHub issue.
- False positive: code/content where the word
TODO is intentional functionality or data (for example, search patterns, parser tests, sample text, or literal matching logic).
- Group actionable TODOs that describe the same underlying problem into one group.
- Make sure GitHub CLI is authenticated for issue creation:
$ gh auth status
If not authenticated, ask the user to run:
$ gh auth login
- For each actionable TODO group, create one GitHub issue with:
- A concise, actionable title.
- A body including:
- Problem description.
- Why it matters.
- Affected code locations as commit-specific, line-specific links.
- Use
gh to create each issue, for example:
$ gh issue create --title "<title>" --body "<body>"
- Replace each corresponding actionable TODO marker in code:
- From:
TODO or TODO:.
- To:
TODO[#<issue-number>]: (the text that originally followed TODO or TODO: must stay unchanged, i.e. TODO[#<issue-number>]: <original text>).
- For false positives, add
IgnoreTODO exclusion regions around the smallest safe code fragment:
- Use
IgnoreTODO-Start and IgnoreTODO-End on separate lines with the file's comment syntax.
- Never place a TODO and an IgnoreTODO marker on the same line.
- Do not nest ignore regions, and always close each
IgnoreTODO-Start.
- Do not create a GitHub issue for TODOs intentionally excluded this way.
- Commit changes, but do not push:
- Run Todosaurus again and ensure there are no warnings except the optional local warning about no GitHub token found (
GITHUB_TOKEN/GH_TOKEN).
Code link format for issue body
Use commit-specific and line-specific GitHub links so previews render correctly:
https://github.com/<owner>/<repo>/blob/<commit-sha>/<path>#L<start>-L<end>
(-L<end> is optional if the TODO is on a single line.)
Example:
https://github.com/ForNeVeR/Todosaurus/blob/0123456789abcdef0123456789abcdef01234567/cli/Cli/Program.fs#L42-L56
When multiple TODOs are mapped to one issue, include all corresponding links in that issue body.
