Agent skill

Systematic Debugging and Investigation

by withkynam in withkynam/vibecode-pro-max-kit

Forces root-cause investigation before any fix, combining a four-phase debugging method with log, CI and performance investigation techniques and a rule against unverified completion claims.

MITAuto-check passedDevelopment

Install Systematic Debugging and Investigation

skills CLI
$ npx skills add withkynam/vibecode-pro-max-kit --skill vc-debug -a claude-code

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

GitHub CLI
$ gh skill install withkynam/vibecode-pro-max-kit vc-debug --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/withkynam/vibecode-pro-max-kit.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/vc-debug .claude/skills/vc-debug && 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
vc-debug
GitHub stars
1.1k
Token cost
~1.5k tokens
SKILL.md length
549 words
Files
13 (incl. scripts, references)
Skills in repo
32
Repo updated
First seen
Licence
MIT

At a glance

Forces root-cause investigation before any fix, combining a four-phase debugging method with log, CI and performance investigation techniques and a rule against unverified completion claims.

  • Works in 10 steps: Systematic Debugging… → Root Cause Tracing… → Defense-in-Depth… → …
  • Debugging a test failure, bug or unexpected behavior from its root cause
  • SKILL.md covers Core Principle, When to Use, Techniques and Quick Reference, plus 2 more sections
  • Runs Shell scripts from its folder

What it does

The core principle is no fixes without root-cause investigation first, since random fixes waste time and create new bugs. Systematic debugging runs four phases in order, root-cause investigation, pattern analysis, hypothesis testing and implementation, with no fix attempted before the first phase is complete. Root-cause tracing follows a bug backward through the call stack to its original trigger rather than its symptom, and includes a bundled shell script for bisecting test pollution. Defense-in-depth validates at every layer after the root cause is found: entry validation, business logic, environment guards and debug instrumentation.

A verification reference states an iron law, no completion claims without fresh verification evidence, meaning a command is run and its output read before any result is claimed. A five-step investigation methodology, from initial assessment through solution development, applies to system-level incidents such as server errors, CI pipeline failures or multi-component failures, with a separate reference covering log and CI analysis in more depth. Output follows the project's own communication standards: answer first, plain language, no unexplained jargon, and a summary on long responses.

When your agent uses it

  • Debugging a test failure, bug or unexpected behavior from its root cause
  • Investigating a CI pipeline failure, server error or performance regression
  • Bisecting which test is polluting state for another test
  • Verifying a fix actually works before claiming it is done

Example prompts

  • “Find the root cause of this failing test before you touch any code.”
  • “Trace this error back through the call stack to where the bad data originated.”
  • “Run find-polluter.sh to figure out which test is leaking state.”

Requirements

  • A shell environment, to run scripts/find-polluter.sh

Workflow steps

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

  1. Systematic Debugging (references/systematic-debugging.md)
  2. Root Cause Tracing (references/root-cause-tracing.md)
  3. Defense-in-Depth (references/defense-in-depth.md)
  4. Verification (references/verification.md)
  5. Investigation Methodology (references/investigation-methodology.md)
  6. Log & CI/CD Analysis (references/log-and-ci-analysis.md)
  7. Performance Diagnostics (references/performance-diagnostics.md)
  8. Reporting Standards (references/reporting-standards.md)
  9. Task Management (references/task-management-debugging.md)
  10. Frontend Verification (references/frontend-verification.md)

What it can do on your machine

Read from SKILL.md and the folder at commit 3bcb2f9. 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

    Ships 2 files in scripts/ (Shell), which the agent can run.

    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

Systematic Debugging and Investigation loads about 1.5k tokens when it runs, and up to ~11k if it reads all its reference files. Until then it costs about 44 tokens; SKILL.md has 549 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~44
When it runs · the whole SKILL.md, loaded when a task matches
~1.5k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~11k

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); the scripts in this folder are not scanned.

SKILL.md

The full file from withkynam/vibecode-pro-max-kit at commit 3bcb2f9, republished under its MIT licence (© withkynam). 549 words, ~1,454 tokens.

Download SKILL.mdSave it as .claude/skills/vc-debug/SKILL.md (or your agent's skills folder). This skill also uses 12 other files; get the full folder from GitHub.
name
vc-debug
description
Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation.
languages
all
argument-hint
[error or issue description]
trigger_keywords
debug, root cause, investigate, why is this
layer
helper
metadata.author
claudekit
metadata.version
4.0.0

Debugging & System Investigation

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Comprehensive framework combining systematic debugging, root cause tracing, defense-in-depth validation, verification protocols, and system-level investigation (logs, CI/CD, databases, performance).

Core Principle

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Random fixes waste time and create new bugs. Find root cause, fix at source, validate at every layer, verify before claiming success.

When to Use

Code-level: Test failures, bugs, unexpected behavior, build failures, integration problems System-level: Server errors, CI/CD pipeline failures, performance degradation, database issues, log analysis Always: Before claiming work complete

Techniques

1. Systematic Debugging (references/systematic-debugging.md)

Four-phase framework: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. Complete each phase before proceeding. No fixes without Phase 1.

Load when: Any bug/issue requiring investigation and fix

2. Root Cause Tracing (references/root-cause-tracing.md)

Trace bugs backward through call stack to find original trigger. Fix at source, not symptom. Includes scripts/find-polluter.sh for bisecting test pollution.

Load when: Error deep in call stack, unclear where invalid data originated

3. Defense-in-Depth (references/defense-in-depth.md)

Validate at every layer: Entry validation → Business logic → Environment guards → Debug instrumentation

Load when: After finding root cause, need comprehensive validation

4. Verification (references/verification.md)

Iron law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. Run command. Read output. Then claim result.

Load when: About to claim work complete, fixed, or passing

5. Investigation Methodology (references/investigation-methodology.md)

Five-step structured investigation for system-level issues: Initial Assessment → Data Collection → Analysis → Root Cause ID → Solution Development

Load when: Server incidents, system behavior analysis, multi-component failures

6. Log & CI/CD Analysis (references/log-and-ci-analysis.md)

Collect and analyze logs from servers, CI/CD pipelines (GitHub Actions), application layers. Tools: gh CLI, structured log queries, correlation across sources.

Load when: CI/CD pipeline failures, server errors, deployment issues

7. Performance Diagnostics (references/performance-diagnostics.md)

Identify bottlenecks, analyze query performance, develop optimization strategies. Covers database queries, API response times, resource utilization.

Load when: Performance degradation, slow queries, high latency, resource exhaustion

8. Reporting Standards (references/reporting-standards.md)

Structured diagnostic reports: Executive Summary → Technical Analysis → Recommendations → Evidence

Load when: Need to produce investigation report or diagnostic summary

Show full SKILL.md (211 more words)Show less
9. Task Management (references/task-management-debugging.md)

Track investigation pipelines via Claude Native Tasks (TaskCreate, TaskUpdate, TaskList). Hydration pattern for multi-step investigations with dependency chains and parallel evidence collection. Fallback: Task tools are CLI-only — if unavailable (VSCode extension), use TodoWrite for tracking. Debug workflow remains fully functional.

Load when: Multi-component investigation (3+ steps), parallel log collection, coordinating debugger subagents

10. Frontend Verification (references/frontend-verification.md)

Visual verification of frontend implementations via Chrome MCP (Claude Chrome Extension) or vc-agent-browser skill fallback. Detect if frontend-related → check Chrome MCP availability → screenshot + console error check → report. Skip if not frontend.

Load when: Implementation touches frontend files (tsx/jsx/vue/svelte/html/css), UI bugs, visual regressions

Quick Reference

Code bug       → systematic-debugging.md (Phase 1-4)
  Deep in stack  → root-cause-tracing.md (trace backward)
  Found cause    → defense-in-depth.md (add layers)
  Claiming done  → verification.md (verify first)

System issue   → investigation-methodology.md (5 steps)
  CI/CD failure  → log-and-ci-analysis.md
  Slow system    → performance-diagnostics.md
  Need report    → reporting-standards.md

Frontend fix   → frontend-verification.md (Chrome/devtools)

Tools Integration

  • Database: sqlite3 CLI and drizzle-kit studio for SQLite/libSQL diagnostics
  • CI/CD: gh CLI for GitHub Actions logs and pipeline debugging
  • Codebase: vc-docs-seeker skill for package/plugin docs; vc-scout skill for codebase exploration
  • Scouting: /vc-scout or /vc-scout ext for finding relevant files
  • Frontend: Chrome browser or vc-agent-browser skill for visual verification (screenshots, console, network)
  • Skills: Activate vc-problem-solving skill when stuck on complex issues

Red Flags

Stop and follow process if thinking:

  • "Quick fix for now, investigate later"
  • "Just try changing X and see if it works"
  • "It's probably X, let me fix that"
  • "Should work now" / "Seems fixed"
  • "Tests pass, we're done"

All mean: Return to systematic process.

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

Files

SKILL.md and 12 other files (scripts, references) in .claude/skills/vc-debug of withkynam/vibecode-pro-max-kit.

  • SKILL.md
  • references/defense-in-depth.md
  • references/frontend-verification.md
  • references/investigation-methodology.md
  • references/log-and-ci-analysis.md
  • references/performance-diagnostics.md
  • references/reporting-standards.md
  • references/root-cause-tracing.md
  • references/systematic-debugging.md
  • references/task-management-debugging.md
  • references/verification.md
  • scripts/find-polluter.sh
  • scripts/find-polluter.test.md

Open the folder on GitHubat commit 3bcb2f9

Compare with similar skills

Systematic Debugging and Investigation 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.

Systematic Debugging and Investigation compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Systematic Debugging and Investigation this skillwithkynam/vibecode-pro-max-kit1.1k—~1.5kAutomated safety check: PassMIT
OpenLogi macOS Permissions TriageAprilNEA/OpenLogi23k—~2.5kAutomated safety check: NotesApache-2.0
Bug Finder for daisyUIsaadeghi/daisyui43k—~2.3kAutomated safety check: PassMIT
Root Cause Debugginggarrytan/gstack136k—~1.4kAutomated safety check: PassMIT
Graph-Based Bug Tracingtirth8205/code-review-graph32k1 repos~287Automated safety check: PassMIT
Systematic DebuggingChrisWiles/claude-code-showcase6.1k3 repos~1.2kAutomated safety check: PassNone

Similar skills

  • Decides whether an OpenLogi device problem on macOS is a privacy-permission (TCC) problem, using agent log lines, and says which identity needs which grant.

    23k GitHub stars~2.5k tokensUpdated 4 days ago
    DevelopmentAuto-check: notes
  • Bug Finder for daisyUI

    saadeghi/daisyui

    Investigates suspected bugs in the daisyUI monorepo through read-only analysis, then writes a decision-ready fix plan in tmp/bugs without changing any product code.

    43k GitHub stars~2.3k tokensUpdated 8 days ago
    DevelopmentAuto-check passed
  • Root Cause Debugging

    garrytan/gstack

    Investigates bugs, errors and stack traces in phases and requires a root-cause hypothesis to be confirmed before any fix is written.

    136k GitHub stars~1.4k tokensUpdated today
    DevelopmentAuto-check passed
  • Graph-Based Bug Tracing

    tirth8205/code-review-graph

    Traces a bug through a code knowledge graph, following callers, callees and execution flow before opening source files, within a small token budget.

    32k GitHub starsUsed in 1 repo~287 tokens
    DevelopmentAuto-check passed
  • Systematic Debugging

    ChrisWiles/claude-code-showcase

    Applies a four-phase debugging routine that finds the root cause of a bug or failing test before any fix is written.

    6.1k GitHub starsUsed in 3 repos~1.2k tokens
    DevelopmentAuto-check passed
  • Debugging and Error Recovery

    addyosmani/agent-skills

    Applies a stop-the-line rule and a step-by-step triage when tests fail, builds break or something stops working, aiming at the root cause instead of guesses.

    103k GitHub starsUsed in 1 repo~2.6k tokens
    DevelopmentAuto-check passed

More from withkynam/vibecode-pro-max-kit

All 32 skills in this repo
  • Library Documentation Seeker

    withkynam/vibecode-pro-max-kit

    Looks up library and framework documentation through Context7 first, with bundled Node scripts as a fallback that fetch and analyze llms.txt files.

    1.1k GitHub starsUsed in 2 repos~1k tokens
    Auto-check: notes
  • Vc Sequential Thinking

    withkynam/vibecode-pro-max-kit

    Apply step-by-step analysis for complex problems with revision capability.

    1.1k GitHub starsUsed in 2 repos~854 tokens
    Auto-check passed
  • Agent Browser Automation

    withkynam/vibecode-pro-max-kit

    Drives a browser through the agent-browser CLI, using compact snapshots with element refs to keep context small in long sessions, plus video recording and cloud browsers.

    1.1k GitHub stars~2.6k tokensUpdated 3 mo ago
    Auto-check passed
  • Context Routing Audit

    withkynam/vibecode-pro-max-kit

    Audits a project's context routing, skill discoverability and skill wiring by running a chain of validator scripts and fixing whatever they report.

    1.1k GitHub stars~1.2k tokensUpdated 3 mo ago
    Auto-check passed
  • Active Plan Audit

    withkynam/vibecode-pro-max-kit

    Reviews a codebase's active plan files for staleness and completion, then archives only the ones confirmed done or obsolete against the real code.

    1.1k GitHub stars~757 tokensUpdated 3 mo ago
    Auto-check passed
  • Repository Context Generator

    withkynam/vibecode-pro-max-kit

    Generates or refreshes a project's shared repository context file so both Codex and Claude work from the same up-to-date knowledge layer.

    1.1k GitHub stars~817 tokensUpdated 3 mo ago
    Auto-check passed

Categories

Questions about Systematic Debugging and Investigation

What does Systematic Debugging and Investigation do?

Forces root-cause investigation before any fix, combining a four-phase debugging method with log, CI and performance investigation techniques and a rule against unverified completion claims. The core principle is no fixes without root-cause investigation first, since random fixes waste time and create new bugs. Systematic debugging runs four phases in order, root-cause investigation, pattern analysis, hypothesis testing and implementation, with no fix attempted before the first phase is complete.

When should I use Systematic Debugging and Investigation?

Systematic Debugging and Investigation fits situations like: debugging a test failure, bug or unexpected behavior from its root cause; investigating a CI pipeline failure, server error or performance regression; bisecting which test is polluting state for another test; verifying a fix actually works before claiming it is done.

How do I install Systematic Debugging and Investigation in Claude Code?

Run `npx skills add withkynam/vibecode-pro-max-kit --skill vc-debug -a claude-code`. Or copy the skill folder (.claude/skills/vc-debug in withkynam/vibecode-pro-max-kit) into .claude/skills/vc-debug in your project. Claude Code loads it when a task matches its description.

How do I install Systematic Debugging and Investigation in Codex?

Run `npx skills add withkynam/vibecode-pro-max-kit --skill vc-debug -a codex`. Or copy the skill folder (.claude/skills/vc-debug in withkynam/vibecode-pro-max-kit) into .agents/skills/vc-debug in your project. Codex loads it when a task matches its description.

Can I use Systematic Debugging and Investigation 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 withkynam/vibecode-pro-max-kit --skill vc-debug -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/vc-debug, .gemini/skills/vc-debug, .github/skills/vc-debug and .opencode/skills/vc-debug in your project.

What does Systematic Debugging and Investigation need to run?

Going by SKILL.md and its folder, Systematic Debugging and Investigation needs a shell for the scripts in its folder. Our summary lists: A shell environment, to run scripts/find-polluter.sh.

Does Systematic Debugging and Investigation 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 Systematic Debugging and Investigation 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. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Systematic Debugging and Investigation use?

Systematic Debugging and Investigation 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 Systematic Debugging and Investigation use?

About 1.5k tokens (SKILL.md is roughly 5.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 9.6k tokens, read only when the agent opens those files.

What are the alternatives to Systematic Debugging and Investigation?

Skills that share tags, products or a category with Systematic Debugging and Investigation: OpenLogi macOS Permissions Triage (AprilNEA/OpenLogi, 23k stars), Bug Finder for daisyUI (saadeghi/daisyui, 43k stars), Root Cause Debugging (garrytan/gstack, 136k stars) and Graph-Based Bug Tracing (tirth8205/code-review-graph, 32k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Systematic Debugging and Investigation?

withkynam (a GitHub user) maintains it in withkynam/vibecode-pro-max-kit, which has 1,145 GitHub stars. The repository holds 32 skills in this directory. The repository was last updated on June 21, 2026.

Source: withkynam/vibecode-pro-max-kit on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.