issue-tracking

Issue Tracking

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.

Core Rule

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.

Storage

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.

Workflow

1. Detect tracker mode

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:

• local issue files under docs/superpowers/issues/*.md
• gh CLI availability
• GitHub authentication
• GitHub repository context
• gh issue list results
• existing GitHub labels from gh label list --json name,description,color when issue listing succeeds

Expected modes:

• hybrid: local issues and GitHub issues both exist
• local: local issue files exist and GitHub is unavailable or empty
• github: GitHub issues exist and no local issue files exist
• empty-github: GitHub is available but there are no local or GitHub issues yet
• empty-local: GitHub is unavailable and there are no local issues yet
• ambiguous: detection produced conflicting or incomplete signals

If mode is ambiguous, ask the user whether to use local-only, GitHub-first, or linked hybrid tracking.

2. Accidental activation guard

If this skill activates while debugging a problem and no documented issue exists:

1. Do not create an issue automatically.
2. Say that no existing issue context was found.
3. Ask: "Do you want me to create a durable issue record for this debugging task, or continue normal debugging without issue tracking?"
4. If the user declines, exit this workflow and use systematic-debugging if debugging remains relevant.
5. If the user agrees, create a local issue record before proceeding.

3. Select or create the issue

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.

4. Triage fields

Capture enough detail to make the issue useful across sessions:

• title
• status
• severity and priority
• source/context
• reproduction steps
• expected behavior
• actual behavior
• evidence/logs
• hypotheses/root cause
• links to files, commits, PRs, or GitHub issues
• comma-separated labels, stored locally as frontmatter like 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 triaged
• triaged: symptoms, impact, and next step are understood
• in-progress: investigation or implementation is underway
• blocked: progress is waiting on external input or dependency
• fixed: implementation change is complete, but verification is not complete yet
• verified: the fix is proven, but the issue intentionally remains open for an external lifecycle reason
• closed: the fix is verified and nothing remains to track

resolved is accepted as an input alias and normalized to closed.

5. Lifecycle updates

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:

• awaiting user, maintainer, or product acceptance
• awaiting deployment, release, or package validation
• needing production or post-release monitoring
• verified locally but not yet verified in the target environment
• keeping a linked GitHub issue open for coordination
• tracking an incomplete follow-up checklist

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.

6. GitHub integration

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.

7. Delegate to other Superpowers workflows

Use this skill to manage the issue record, then delegate the work:

• Use systematic-debugging for root-cause investigation.
• Use brainstorming if the issue becomes feature or behavior design work.
• Use writing-plans / executing-plans for multi-step fixes.
• Use verification-before-completion before marking verified or closed.

Completion Checklist

Before reporting that issue-tracking work is complete:

• The relevant issue exists or the user explicitly chose not to create one.
• The issue status reflects current reality.
• Work performed is logged.
• Verification evidence is recorded before verified or closed.
• GitHub writes, if any, were explicitly confirmed.
• docs/superpowers/issues/README.md is regenerated when local issue files changed:

node skills/issue-tracking/scripts/issue.mjs index