/todo¶
File open roadmap items and inline TODO/FIXME/HACK/XXX comments as GitHub
issues, instead of just printing a status report.
What It Does¶
- Verifies
ghis authenticated and the current directory is a GitHub repo. - Scans for open work:
- Roadmap/TODO files in common locations (
TODO.md,docs/TODO.md,docs/research/todo.md,ROADMAP.md) — items not marked done. - Inline
TODO,FIXME,HACK,XXXmarkers in source, excluding vendored and generated directories.
- Roadmap/TODO files in common locations (
- Dedupes against existing GitHub issues (open and closed) using a hidden
<!-- todo-source: file:line -->marker embedded in each issue body, so reruns don't create duplicates. - Drafts a proposed issue per remaining item: a conventional-commit-style title,
a body with the source location and context, and labels (
bug,tech-debt,enhancement,priority:*) — creating any missing standard labels first. - Shows the full proposed batch and waits for confirmation before creating anything on GitHub.
- Creates the confirmed issues with
gh issue create, retrying once on failure. - Reports what was created, what was already tracked, and what failed.
- Optionally — only if you say yes — updates the inline comments to reference
the new issue number (
TODO(#123): ...) for traceability.
Example¶
Typical flow:
Scanning docs/research/todo.md and source for TODO/FIXME/HACK/XXX...
Found 6 roadmap items, 4 inline markers.
3 already tracked by existing issues (skipped).
Proposed issues:
fix: handle IB Gateway daily disconnect at 11:45 PM ET [bug, priority:medium]
src/broker/client.py:142
refactor: extract retry logic out of order placement [tech-debt]
src/execution/engine.py:87
feat: add Telegram alert for circuit breaker reset [enhancement]
docs/research/todo.md
Create these 3 issues? (y/n)
Notes¶
- Nothing is written to GitHub until you confirm the batch — this is a shared-state, visible action, not a read-only report.
- One issue per discrete item; unrelated TODOs are never bundled together.
- If a PR resolves one of these issues, include
Closes #<issue>in the PR body (see PR Workflow) so merging it closes the issue automatically. - Requires the
ghCLI, authenticated (gh auth status).