vc-debug
Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- vc-debug
- layer
- helper
- metadata
- { "author": "claudekit", "version": "4.0.0" }
- languages
- all
- description
- Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation.
- argument-hint
- [error or issue description]
- trigger_keywords
- debug, root cause, investigate, why is this
02 资源文件 11
- 参考文档references/defense-in-depth.md3.6 KB
- 参考文档references/frontend-verification.md3.6 KB
- 参考文档references/investigation-methodology.md4.0 KB
- 参考文档references/log-and-ci-analysis.md3.4 KB
- 参考文档references/performance-diagnostics.md3.8 KB
- 参考文档references/reporting-standards.md2.9 KB
- 参考文档references/root-cause-tracing.md3.3 KB
- 参考文档references/systematic-debugging.md4.1 KB
- 参考文档references/task-management-debugging.md5.6 KB
- 参考文档references/verification.md3.3 KB
- 脚本scripts/find-polluter.test.md2.1 KB
03 SKILL.md 正文
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
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:
sqlite3CLI anddrizzle-kit studiofor SQLite/libSQL diagnostics - CI/CD:
ghCLI for GitHub Actions logs and pipeline debugging - Codebase:
vc-docs-seekerskill for package/plugin docs;vc-scoutskill for codebase exploration - Scouting:
/vc-scoutor/vc-scout extfor finding relevant files - Frontend: Chrome browser or
vc-agent-browserskill for visual verification (screenshots, console, network) - Skills: Activate
vc-problem-solvingskill 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.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.