From superpowers
Use when the user asks to track, triage, manage, sync, update, or review issues; mentions issue tracking, GitHub issues, regressions/errors needing status tracking, or asks to keep a durable record of bug/issue lifecycle. Do not use for every ordinary bugfix unless the user asks to track it or multiple issues need coordination.
How this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers:issue-trackingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill to keep a durable issue ledger across debugging, fixing, verification, and optional GitHub Issue sync.
Use this skill to keep a durable issue ledger across debugging, fixing, verification, and optional GitHub Issue sync.
This is a front-door workflow for issue management. It should not hijack ordinary bugfixing. If the user only wants to debug one problem and did not ask for durable tracking, use systematic-debugging instead.
Local issue files are the durable work log. GitHub Issues are optional linked/public records. GitHub reads are allowed for detection and listing. The first GitHub write requires explicit user confirmation.
Local issues live in the active workspace at:
docs/superpowers/issues/
Use the helper script from the package skill directory:
node skills/issue-tracking/scripts/issue.mjs <command>
If running from outside the Superpowers package, use the absolute path to this skill's scripts/issue.mjs file while keeping the current working directory set to the project whose issues are being tracked.
Run:
node skills/issue-tracking/scripts/issue.mjs detect
Use the detected mode unless it is ambiguous. Treat detect as the initial issue inventory; it already includes local issues, GitHub issues, and discovered GitHub labels when available. Do not immediately run list or list --all after detect unless you need a refreshed view after changes or a different scope such as closed issues.
The detector considers:
docs/superpowers/issues/*.mdgh CLI availabilitygh issue list resultsgh label list --json name,description,color when issue listing succeedsExpected modes:
hybrid: local issues and GitHub issues both existlocal: local issue files exist and GitHub is unavailable or emptygithub: GitHub issues exist and no local issue files existempty-github: GitHub is available but there are no local or GitHub issues yetempty-local: GitHub is unavailable and there are no local issues yetambiguous: detection produced conflicting or incomplete signalsIf mode is ambiguous, ask the user whether to use local-only, GitHub-first, or linked hybrid tracking.
If this skill activates while debugging a problem and no documented issue exists:
systematic-debugging if debugging remains relevant.First use the issues returned by detect to select an existing record or identify duplicates. Run a separate list command only when the detect output is stale, too narrow for the task, or you explicitly need a different scope:
node skills/issue-tracking/scripts/issue.mjs list # active issues only
node skills/issue-tracking/scripts/issue.mjs list --closed # closed issues only
node skills/issue-tracking/scripts/issue.mjs list --all # active and closed issues
Create a new record when needed:
node skills/issue-tracking/scripts/issue.mjs create --title "Short issue title" --summary "One paragraph summary" --severity medium --priority normal --labels "bug,severity:medium"
Before creating, check for duplicates or related issues in the local list and GitHub list when available.
Capture enough detail to make the issue useful across sessions:
labels: "bug,severity:high"When GitHub labels are discovered, suggest matching existing labels during triage. Obvious severity matches are especially useful: if the repository has labels such as severity:critical, severity:high, severity:medium, or severity:low, suggest the one that matches the triaged severity.
Allowed statuses:
new: issue recorded but not yet triagedtriaged: symptoms, impact, and next step are understoodin-progress: investigation or implementation is underwayblocked: progress is waiting on external input or dependencyfixed: implementation change is complete, but verification is not complete yetverified: the fix is proven, but the issue intentionally remains open for an external lifecycle reasonclosed: the fix is verified and nothing remains to trackresolved is accepted as an input alias and normalized to closed.
Every material action should append a work-log entry:
node skills/issue-tracking/scripts/issue.mjs update ISSUE-0001 --status in-progress --labels "bug,severity:high" --log "Investigated failing command; narrowed failure to config loading."
Use dedicated fields when applicable:
node skills/issue-tracking/scripts/issue.mjs update ISSUE-0001 --evidence "Command output: ..."
node skills/issue-tracking/scripts/issue.mjs update ISSUE-0001 --hypothesis "Likely stale cache after reload."
node skills/issue-tracking/scripts/issue.mjs update ISSUE-0001 --verification "npm test passed after fix."
Do not mark an issue verified or closed unless the record includes verification evidence.
After successful verification, close the issue by default when nothing remains to track:
node skills/issue-tracking/scripts/issue.mjs close ISSUE-0001 --verification "Fixed and verified with npm test."
Use verified instead of closed only when the fix is proven but the issue should intentionally remain open, such as:
When stopping at verified, include the reason it remains open in the verification text:
node skills/issue-tracking/scripts/issue.mjs update ISSUE-0001 --status verified --verification "Local smoke test passed. Keeping open until packaged release validation."
Closing moves the local issue file to:
docs/superpowers/issues/closed/
update ISSUE-0001 --status closed --verification "..." and update ISSUE-0001 --status resolved --verification "..." behave equivalently. Normal list output shows active issues only; use list --closed for closed issues and list --all for both active and closed issues.
GitHub reads can happen automatically through detection/listing.
Before the first GitHub write in a session, ask for explicit confirmation. After confirmation, use:
node skills/issue-tracking/scripts/issue.mjs sync ISSUE-0001 --confirm-github-write
Without --confirm-github-write, sync must not create, edit, label, comment on, or close GitHub issues. create and update are local-only; sync --confirm-github-write is the explicit GitHub write boundary.
When a linked local issue has status: closed, confirmed sync closes the linked GitHub issue with a closing comment. If a local issue is already closed but has no linked GitHub issue, sync must not create a new GitHub issue just to close it.
GitHub label behavior is existing-label-only. Keep any local comma-separated labels in the issue file, but only apply labels that were discovered from the repository. Unknown labels are ignored for GitHub paths; do not create missing GitHub labels automatically.
Avoid spamming GitHub. Keep detailed investigation logs local. Sync concise summaries, links, labels, closure, and important status changes.
Use this skill to manage the issue record, then delegate the work:
systematic-debugging for root-cause investigation.brainstorming if the issue becomes feature or behavior design work.writing-plans / executing-plans for multi-step fixes.verification-before-completion before marking verified or closed.Before reporting that issue-tracking work is complete:
verified or closed.docs/superpowers/issues/README.md is regenerated when local issue files changed:node skills/issue-tracking/scripts/issue.mjs index
npx claudepluginhub justinmok/pi-superpowers --plugin superpowersGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.