From git-workflow-guards
Read-only repo-health scan. Use when running a manual repo-health pass to surface stale tech-debt markers. Finds `TODO`/`FIXME`/`XXX`/`HACK` comments where `git blame` shows the introducing commit is more than 30 days old, then files one tracker issue per finding with the original commit's sha/author/date/subject. Never edits source. Tracker-agnostic.
How this skill is triggered — by the user, by Claude, or both
Slash command
/git-workflow-guards:gc-stale-todosThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are running as a **garbage-collection agent** for this repo. Your single job in this session is to find stale `TODO` / `FIXME` / `XXX` / `HACK` comments and file one tracker issue per finding, with the original commit context (sha, author, date, subject). You are not fixing anything — you are surfacing findings so a human (or a future agent) can later schedule the work.
You are running as a garbage-collection agent for this repo. Your single job in this session is to find stale TODO / FIXME / XXX / HACK comments and file one tracker issue per finding, with the original commit context (sha, author, date, subject). You are not fixing anything — you are surfacing findings so a human (or a future agent) can later schedule the work.
Run on a manual cadence (cron-eligible, weekly is sensible) against a clean checkout. Not human-invoked at action boundaries.
Find inline-comment markers that have been sitting in the codebase for more than 30 days and open one tracker issue per finding with the original commit's context, so a future reader can decide whether the marker is still relevant.
A line containing one of TODO, FIXME, XXX, or HACK (case-sensitive, as comment text — not as a string literal in test data or fixture content) where git blame shows the original commit is more than 30 days old relative to today.
A marker is "stale" when:
// HACK history: removed in 2024).All source files in the repo. Use a comment-aware grep (covering //, /* */, #, <!-- -->, ; comment styles) across the working tree.
Do not open issues for markers that fall into these buckets:
node_modules/, .git/, dist/, build/, .next/, target/, vendor/, or files containing // AUTO-GENERATED / // DO NOT EDIT / # AUTO-GENERATED headers. Also skip declarations files (*.d.ts).expect(text).toBe('TODO: write me') is data, not a real TODO. Verify the marker is in a comment context (//, /* */, <!-- -->, #, ;) before counting it.**/__fixtures__/, **/fixtures/, **/*.fixture.*. Test data may contain TODO-like strings as part of mock content.// FIXME (closed 2023): we used to ... or // TODO history is documentation of past intent, not pending work. Skip.git blame -L <line>,<line> --porcelain -- <file> to read the line's author-time. If it's within the last 30 days, skip — the author is still actively iterating. Do not use git log -1 -- <file> for this; see workflow step 3 for why.// TODO: refactor this someday with no concrete action is low signal. Only file when the marker names a specific thing to do or fix. If you can't summarize the work in one short sentence, the marker is too vague — skip.#42, JIRA-123, GH-99, bd-xxx), the work is already tracked. Skip.When in doubt: don't open the issue. The point of this scan is to surface debt that has quietly slipped past the team's attention. Markers that are actively-tracked, deliberately-left, or trivially-vague are not the target.
For each candidate marker, capture:
today - commit_date.TODO | FIXME | XXX | HACK. (FIXME and HACK are higher priority signals than TODO.)do-the-work — the marker is concrete and the work is small. The issue becomes the work item.gate-and-monitor — the marker calls out a known limitation; the right next step is to add a metric or test that fires when the limitation actually bites.delete-as-stale — the marker references a system/feature that no longer exists, or describes work that is no longer relevant.Only file an issue when age ≥ 30 days AND the marker is specific (per guardrail 7) AND it isn't already linked to a tracker.
This skill is tracker-agnostic. The repo's project tracker may be GitHub Issues (gh issue create), Linear, Jira, beads (bd create), or a plain markdown report. Detect what the project uses in this priority order and use the first match:
.beads/ directory at the repo root → bd create.gh auth status succeeds and gh repo view --json hasIssuesEnabled -q .hasIssuesEnabled returns true → gh issue create.LINEAR_API_KEY env var set → Linear API.JIRA_API_TOKEN env var set → Jira API.Before filing a new issue, check for an existing GC issue covering the same marker (search the tracker for the file path or marker text — bd list --label gc / gh issue list --label gc --search "<file>:<line>"). If a match exists, skip — don't file duplicates on every weekly run.
The payload shape is the same regardless of tracker:
Stale <TYPE>: <one-line summary of what the comment says> (one short imperative sentence; this is the issue's headline)Body template:
**Location:** `path/to/file.ts:42`
**Marker:** `// TODO: <verbatim comment text>`
**Age:** 187 days | **Type:** TODO
**Origin:** commit `abc1234` by Author Name on 2025-10-23 — "Original commit subject"
**What the comment is asking for:** <2–3 sentences describing the work in your own words, having read the surrounding code>
**Suggested action:** do-the-work
**Why this is still relevant (or isn't):** <1 sentence — has the world moved past this marker, or is the work still pending? If no longer relevant, set suggested action to delete-as-stale and explain why.>
_Filed by gc-stale-todos skill._
If the tracker supports labels, add gc and stale-todo. If not, embed them as a **Labels:** gc, stale-todo line in the body.
If no tracker is wired up, write the findings to gc-findings/stale-todos-<YYYY-MM-DD>.md at the repo root and tell the user where the report landed.
TODO, FIXME, XXX, HACK). Capture file + line for every hit. For each surviving hit, run git blame -L <line>,<line> --porcelain -- <file> and read the author-time (Unix timestamp), sha, author, and summary from the porcelain output. Do not use git log -1 -- <file> — it returns the file's most recent commit, which is misleading: a file touched yesterday would mark every old TODO in it as "recent." git blame is line-accurate; git log is file-accurate.do-the-work / gate-and-monitor / delete-as-stale).(age × marker_severity) where FIXME/HACK outrank TODO/XXX. File one issue per surviving finding via the project's tracker. Print the issue IDs (or report path) as you go.delete-as-stale. Your output is only the issues and a final summary printed to stdout.After filing, print:
=== gc-stale-todos summary ===
Filed N issues:
<id-or-path> <title> (age: D days, type: TODO|FIXME|XXX|HACK)
...
Skipped M candidates (reasons):
<one-line reason per skip, grouped — e.g., "5× recent (≤30 days)", "3× linked to existing issue", "2× too vague">
The skip list is itself useful signal — if every run skips the same category, that's a hint to update the guardrails in this skill.
grep, ls, cat, find, git log, git blame, git show, git diff) plus the tracker's read+create commands needed for filing and dedupe. For GitHub Issues that means gh repo view, gh issue list, gh issue view, gh issue create, gh label list, gh label create --force. For beads, bd list, bd show, bd create, bd label add. No git commit, no git push, no writes to the filesystem outside the tracker call (or the fallback markdown report).npx claudepluginhub zainrizvi/git-workflow-guards --plugin git-workflow-guardsProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.