New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Bug Investigator

by MageByte-Zero in MageByte-Zero/spec-superflow

A skill your agent uses when encountering any bug, test failure, or unexpected behavior during spec-superflow execution, before proposing fixes.

MITAuto-check passedDevelopment

Install Bug Investigator

skills CLI
$ npx skills add MageByte-Zero/spec-superflow --skill bug-investigator -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install MageByte-Zero/spec-superflow bug-investigator --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/MageByte-Zero/spec-superflow.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/bug-investigator .claude/skills/bug-investigator && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
bug-investigator
GitHub stars
841
Used in
1 other repo
Token cost
~1.6k tokens
SKILL.md length
847 words
Files
1
Skills in repo
9
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when encountering any bug, test failure, or unexpected behavior during spec-superflow execution, before proposing fixes.

  • Works in 4 steps: Root Cause Investigation → Pattern Analysis → Hypothesis and Testing → …
  • Encountering any bug
  • SKILL.md covers Bundled runtime, New direct/planned changes, The Iron Law and When to Use, plus 5 more sections
  • Calls node

What it does

Bug Investigator is an agent skill from MageByte-Zero/spec-superflow. Use when encountering any bug, test failure, or unexpected behavior during spec-superflow execution, before proposing fixes. Invoked automatically when build-executor hits a blockage.

Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development, covering Failing and flaky tests. The repository describes itself as: 源码级融合 OpenSpec 规划引擎 + Superpowers 执行纪律的 AI 编程工作流插件。17 平台支持，9 skills，Spec-first，契约驱动。 The licence is MIT.

When your agent uses it

  • Encountering any bug
  • Unexpected behavior during spec-superflow execution
  • Before proposing fixes

Example prompts

  • “/bug-investigator”

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Root Cause Investigation
  2. Pattern Analysis
  3. Hypothesis and Testing
  4. Implementation

What it can do on your machine

Read from SKILL.md and the folder at commit 25d9b0c. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • node

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Bug Investigator loads about 1.6k tokens when it runs. Until then it costs about 50 tokens; SKILL.md has 847 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~50
When it runs · the whole SKILL.md, loaded when a task matches
~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from MageByte-Zero/spec-superflow at commit 25d9b0c, republished under its MIT licence (© MageByte-Zero). 847 words, ~1,628 tokens.

Download SKILL.mdSave it as .claude/skills/bug-investigator/SKILL.md (or your agent's skills folder).
name
bug-investigator
description
Use when encountering any bug, test failure, or unexpected behavior during spec-superflow execution, before proposing fixes. Invoked automatically when build-executor hits a blockage.

Bug Investigator

Bundled runtime

Before executing a CLI line below, replace its leading SSF with node "<plugin-root>/scripts/spec-superflow.mjs"; <plugin-root> is the absolute directory two levels above this file. Never run SSF literally or call an ssf from PATH.

Core principle: Find root cause before attempting fixes. Symptom fixes are failure.

New direct/planned changes

Investigate in executing without a phase transition or a separate debug ledger: reproduce, trace the root cause, make one focused repair and verify. Keep useful failure evidence in the existing progress entry. Three failures for the same unresolved issue warrant a decision; unrelated findings do not accumulate a shared budget. No task book or subagent is required. The detailed legacy protocol below is for an existing debugging state or an investigation that needs it.

The Iron Law

No fixes without root cause investigation first. If you haven't completed Phase 1, you cannot propose fixes.

When to Use

Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures, integration issues. Especially when under time pressure, "one quick fix" seems obvious, you've already tried multiple fixes, or you don't fully understand the issue.

Don't skip because issue "seems simple" or you're "in a hurry" — systematic debugging is faster than thrashing.

The Four Phases

Complete each phase before proceeding.

Phase 1: Root Cause Investigation
  1. Read error messages carefully: stack traces, line numbers, file paths, error codes — they often contain the exact solution
  2. Reproduce consistently: exact steps, every time? If not reproducible → gather more data, don't guess
  3. Check recent changes: git diff, recent commits, new dependencies, config changes, environment differences
  4. Multi-component systems: add diagnostic instrumentation at each component boundary. Log what enters and exits each layer. Run once to gather evidence, then analyze which component fails
  5. Trace data flow: backward tracing — where does the bad value originate? Keep tracing up until you find the source. Fix at source, not symptom
Phase 2: Pattern Analysis
  1. Find working examples of similar code in the same codebase
  2. Compare against references — read reference implementation completely
  3. Identify every difference between working and broken, however small
  4. Understand dependencies: other components, settings, config, environment, assumptions
Phase 3: Hypothesis and Testing

Scientific method: form a single hypothesis ("I think X is the root cause because Y"), test with the smallest possible change (one variable at a time), verify before continuing. If it didn't work, form a NEW hypothesis — don't add more fixes. When you don't know, say so and ask for help.

Phase 4: Implementation
  1. Create failing test case — simplest reproduction, automated if possible. Follow TDD rules from build-executor
  2. Implement single fix — address root cause, one change at a time, no "while I'm here" improvements
  3. Verify fix — test passes? no regressions? issue resolved?
  4. If fix doesn't work: count attempts. < 3 → return to Phase 1. ≥ 3 → STOP and question architecture (DP-5)
Show full SKILL.md (370 more words)Show less
DP-5: Debug Escalation (3+ Failures)

3+ failed fixes = architectural problem. Each fix revealing new problems elsewhere = wrong architecture.

After every failed fix, preserve its failure output in a physical file inside the change directory, then record the distinct attempt:

Full and legacy Hotfix require a current, valid execution plan before this command; establish one with SSF execution recommend and SSF execution plan if needed. Quick, Tweak, lightweight, and direct Hotfix keep their planless contract: their valid workflow receipt authorizes debugging, and the ledger binds attempts to that receipt plus the current workflow, artifact, and contract hashes. The debug command rejects a missing or replaced receipt or a stale required plan.

bash
SSF debug attempt record <change-dir> \
  --id <unique-attempt-id> \
  --summary "<what was tried and why it failed>" \
  --evidence <change-local-failure-log>

Use SSF debug attempt show <change-dir> --json to present the complete attempt ledger. Wave Review repair failures are separate evidence and never count as debugging attempts.

After at least three distinct evidence-backed attempts, stop and discuss the architectural decision with the user. Only after the user explicitly chooses may DP-5 be recorded:

bash
SSF debug escalate <change-dir> \
  --decision <continue|abandon> \
  --reason "<user-confirmed decision>" \
  --confirm

Never write dp_5_* through raw SSF state set; those fields are guarded by the debug ledger. If the user chooses abandon, transition to abandoned only after the guarded DP-5 receipt is recorded.

Red Flags — Return to Phase 1

"Quick fix, investigate later" / "Just try changing X" / "Skip the test, I'll verify manually" / "It's probably X, let me fix that" / "I don't fully understand but this might work" / "One more fix attempt" (after 2+) / Proposing solutions before tracing data flow.

All of these mean: STOP. Return to Phase 1. If 3+ fixes failed, question the architecture.

Quick Reference

PhaseKey ActivitiesSuccess Criteria
1. Root CauseRead errors, reproduce, check changes, gather evidenceUnderstand WHAT and WHY
2. PatternFind working examples, compareIdentify differences
3. HypothesisForm theory, test minimallyConfirmed or new hypothesis
4. ImplementationCreate test, fix, verifyBug resolved, tests pass

When No Root Cause Found

If truly environmental/timing-dependent/external: document what you investigated, implement appropriate handling (retry, timeout, error message), add monitoring. But 95% of "no root cause" cases are incomplete investigation.

Exception Handling

  • Parse failures: Report raw output, ask for clarification — don't guess
  • Missing files: Escalate immediately — not a normal debugging scenario
  • User interruption: Re-read investigation report on resume, continue from last completed phase

© MageByte-Zero, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/bug-investigator of MageByte-Zero/spec-superflow.

Open the folder on GitHubat commit 25d9b0c

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in MageByte-Zero/spec-superflow, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Bug Investigator next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Bug Investigator compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Bug Investigator this skillMageByte-Zero/spec-superflow8411 repos~1.6kAutomated safety check: PassMIT
PR Babysitteropeninterpreter/openinterpreter69k3 repos~4.2kAutomated safety check: PassApache-2.0
Iterate PRmeshery/meshery-operator1518 repos~2.2kAutomated safety check: PassApache-2.0
React Router Bug Fix Workflowremix-run/react-router57k—~1.3kAutomated safety check: PassMIT
Runtime Debugvercel/next.js143k1 repos~618Automated safety check: PassMIT
PlotJuggler Ship CheckPlotJuggler/PlotJuggler6.2k—~1.3kAutomated safety check: PassMPL-2.0

Similar skills

  • PR Babysitter

    openinterpreter/openinterpreter

    Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.

    69k GitHub starsUsed in 3 repos~4.2k tokens
    DevelopmentAuto-check passed

  • Iterate PR

    meshery/meshery-operator

    Iterate on a PR until CI passes. An agent skill from meshery/meshery-operator.

    151 GitHub starsUsed in 8 repos~2.2k tokens
    DevelopmentAuto-check passed

  • React Router Bug Fix Workflow

    remix-run/react-router

    Fixes a React Router bug reported in a GitHub issue end to end: fetching the issue, validating the reproduction, writing a failing test and implementing the fix on a new branch.

    57k GitHub stars~1.3k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Runtime Debug

    vercel/next.js

    Official

    Debug and verification workflow for runtime-bundle and module-resolution regressions.

    143k GitHub starsUsed in 1 repo~618 tokens
    DevelopmentAuto-check passed

  • PlotJuggler Ship Check

    PlotJuggler/PlotJuggler

    Runs a gated finish-line checklist before committing a PlotJuggler PJ4 change: build proof, red-test triage, hooks, docs freshness and a diff self-review.

    6.2k GitHub stars~1.3k tokensUpdated 6 days ago
    DevelopmentAuto-check passed

  • PR Review

    wysaid/android-gpuimage-plus

    Address review comments and CI failures for the current branch's PR

    1.9k GitHub stars~1.4k tokensUpdated 2 mo ago
    DevelopmentAuto-check passed

More from MageByte-Zero/spec-superflow

All 9 skills in this repo

  • Need Explorer

    MageByte-Zero/spec-superflow

    Clarify intent, scope, constraints, and success criteria before artifact creation.

    841 GitHub starsUsed in 1 repo~805 tokens
    Auto-check passed

  • Spec Writer

    MageByte-Zero/spec-superflow

    Create or refine spec-superflow planning artifacts. An agent skill from MageByte-Zero/spec-superflow.

    841 GitHub starsUsed in 1 repo~1.6k tokens
    Auto-check passed

  • Build Executor

    MageByte-Zero/spec-superflow

    Execute an active direct request or approved planned change.

    841 GitHub starsUsed in 1 repo~2.3k tokens
    Auto-check passed

  • Contract Builder

    MageByte-Zero/spec-superflow

    Maintain an execution contract only for an existing legacy change that requires one.

    841 GitHub starsUsed in 1 repo~1.3k tokens
    Auto-check passed

  • Release Archivist

    MageByte-Zero/spec-superflow

    Close out a spec-superflow change with verification, summary, and archive readiness.

    841 GitHub starsUsed in 1 repo~1.3k tokens
    Auto-check passed

  • Workflow Start

    MageByte-Zero/spec-superflow

    Primary entry point for the spec-superflow state-machine workflow.

    841 GitHub starsUsed in 1 repo~1.3k tokens
    Auto-check passed

Categories

Questions about Bug Investigator

What does Bug Investigator do?

A skill your agent uses when encountering any bug, test failure, or unexpected behavior during spec-superflow execution, before proposing fixes. Bug Investigator is an agent skill from MageByte-Zero/spec-superflow. Use when encountering any bug, test failure, or unexpected behavior during spec-superflow execution, before proposing fixes.

When should I use Bug Investigator?

Bug Investigator fits situations like: encountering any bug; unexpected behavior during spec-superflow execution; before proposing fixes.

How do I install Bug Investigator in Claude Code?

Run `npx skills add MageByte-Zero/spec-superflow --skill bug-investigator -a claude-code`. Or copy the skill folder (skills/bug-investigator in MageByte-Zero/spec-superflow) into .claude/skills/bug-investigator in your project. Claude Code loads it when a task matches its description.

How do I install Bug Investigator in Codex?

Run `npx skills add MageByte-Zero/spec-superflow --skill bug-investigator -a codex`. Or copy the skill folder (skills/bug-investigator in MageByte-Zero/spec-superflow) into .agents/skills/bug-investigator in your project. Codex loads it when a task matches its description.

Can I use Bug Investigator in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add MageByte-Zero/spec-superflow --skill bug-investigator -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/bug-investigator, .gemini/skills/bug-investigator, .github/skills/bug-investigator and .opencode/skills/bug-investigator in your project.

What does Bug Investigator need to run?

Going by SKILL.md and its folder, Bug Investigator needs the command-line tools its instructions call (node).

Does Bug Investigator access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Bug Investigator safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Bug Investigator use?

Bug Investigator is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Bug Investigator use?

About 1.6k tokens (SKILL.md is roughly 6.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Bug Investigator?

Skills that share tags, products or a category with Bug Investigator: PR Babysitter (openinterpreter/openinterpreter, 69k stars), Iterate PR (meshery/meshery-operator, 151 stars), React Router Bug Fix Workflow (remix-run/react-router, 57k stars) and Runtime Debug (vercel/next.js, 143k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Bug Investigator?

MageByte-Zero (a GitHub user) maintains it in MageByte-Zero/spec-superflow, which has 841 GitHub stars. The repository holds 9 skills in this directory. The repository was last updated on October 1, 2026.

Source: MageByte-Zero/spec-superflow on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.