debug-session
Chain-combined skill for systematic debugging workflow. Combines bug reproduction judgment, error analysis, execution tracing, and debugging expertise into a complete session规范. Use when user mentions debugging, fixing bugs, something not working, error messages, or when code isn't behaving as expected. Triggers especially when user says "debug this", "why is this broken", "it's not working", "error message", "something went wrong", or "help me find the bug".
- License 许可
- MIT
- 最近更新
- 2026-04-18
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- debug-session
- category
- coding
- combines
- [ "debug-expert", "reproduce-bug", "understand-error", "trace-execution" ]
- priority
- P0
- description
- Chain-combined skill for systematic debugging workflow. Combines bug reproduction judgment, error analysis, execution tracing, and debugging expertise into a complete session规范. Use when user mentions debugging, fixing bugs, something not working, error messages, or when code isn't behaving as expected. Triggers especially when user says "debug this", "why is this broken", "it's not working", "error message", "something went wrong", or "help me find the bug".
- trigger_patterns
- [ "debug this", "why is this broken", "not working", "error message", "something went wrong", "find the bug", "debugging", "it's throwing an error", "null is not", "cannot read property" ]
03 SKILL.md 正文
Debug Session — Systematic Bug Resolution Framework
Overview
Debug-session is a chain-combined behavioral specification skill that merges:
debug-expert— Expert debugging methodologyreproduce-bug— Reliable bug reproductionunderstand-error— Error message interpretationtrace-execution— Execution path tracking
The core judgment it encapsulates: "How do I systematically find and fix this bug without introducing new ones?"
This skill embodies the disciplined approach of an expert debugger: reproducible steps, systematic elimination, and verified fixes.
Core Philosophy
The Debugging Paradox
"The bug is usually where you least expect it — which is exactly why you need to expect it everywhere."
The first rule of debugging: Assume nothing. The bug is in the code you wrote, not in the framework, the language, or cosmic rays.
The Debugging Mindset
┌─────────────────────────────────────────────────────────────┐
│ DEBUGGING MINDSET │
│ │
│ MYSTERIOUS SYSTEMATIC │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────────┐ │
│ │ "How did│ │ Facts first │ │
│ │ this │ │ Hypothesis │ │
│ │ happen?"│ │ then verify │ │
│ └─────────┘ └─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────────┐ │
│ │ Random │ │ Root cause │ │
│ │ poking │ │ identified │ │
│ └─────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
Behavioral Specification
Phase 1: Reproduce the Bug
Rule #1: If you can't reproduce it, you can't fix it.
1.1 Gather Information
Before anything else, collect:
## Bug Report Summary
| Field | Value |
|-------|-------|
| Error message | [exact text] |
| When does it occur? | [steps to reproduce] |
| Frequency | [always/sometimes/once] |
| Environment | [dev/prod/browser/node] |
| Version | [git commit or version] |
1.2 Create Minimal Reproduction
## Reproduction Steps
1. [Step 1 - specific action]
2. [Step 2 - specific action]
3. [Step 3 - specific action]
Expected: [what should happen]
Actual: [what happens instead]
The ideal reproduction:
- Minimal code
- No unrelated code
- Same environment as production
- Can be shared with others
1.3 Verify Reproduction
Before fixing, confirm you can:
- [ ] Make it happen on demand
- [ ] Make it NOT happen when you change something specific
- [ ] Run the exact same steps in a fresh environment
Phase 2: Understand the Error
2.1 Error Message Analysis
┌─────────────────────────────────────────────────────────────┐
│ ERROR MESSAGE DECODER │
│ │
│ Error: "Cannot read property 'name' of undefined" │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ WHERE │ WHAT │ WHY │ │
│ ├───────┼──────┼──────────────────────────────────────┤ │
│ │ Line# │ 'name'│ 'name' property │ │
│ │ │ │ doesn't exist on │ │
│ │ │ │ the object │ │
│ │ │ │ returned from │ │
│ │ │ │ previous function │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Question: Why is the object undefined? │
│ Next: Trace back to find where it should have a value │
└─────────────────────────────────────────────────────────────┘
2.2 Stack Trace Reading
## Stack Trace Analysis
Error: TypeError: Cannot read property 'name'
at User.getFullName (User.ts:45)
└── WHERE: Line 45 of User.ts
at UserController.handleRequest (UserController.ts:89)
└── WHO CALLED: Line 89 of UserController
at Router.dispatch (Router.ts:123)
└── HOW WE GOT HERE: ...
---
Question to ask: "What should be on line 45?"
Answer: A User object with a 'name' property
Question: "Where does the User come from?"
Answer: It's returned from UserController.handleRequest
Conclusion: UserController is passing undefined instead of a User
Phase 3: Trace the Execution
3.1 Follow the Data
# Find where data is created
grep -r "createUser" --include="*.ts" src/
# Find where data flows
grep -r "getFullName" --include="*.ts" src/
3.2 State Inspection Points
## Data Flow Map
Router ──► Controller ──► Service ──► Database
│
▼
[User object]
│
▼
[Middleware?] ──► Adds auth?
│
▼
[Handler] ──► Line 45: user.getFullName()
│
▼
ERROR: user is undefined
│
▼
WHY: Middleware didn't run?
WHY: Service returned null?
WHY: Database query failed?
3.3 Breakpoint Strategy
Where to break:
- Where the error occurs (line 45)
- One step before (Controller line 89)
- Where the data is created (Service)
- Entry point (Router)
What to check at each:
- Variables exist
- Variables have expected values
- Functions return expected types
Phase 4: Form Hypothesis
Rule #2: If you think you found it, prove it.
4.1 Hypothesis Template
## Hypothesis
I believe the bug is caused by:
[Specific code or condition]
My reasoning:
1. [Observation 1]
2. [Observation 2]
3. [Conclusion]
To verify this hypothesis, I will:
[Specific test or check]
If I'm right, [expected outcome]
If I'm wrong, [expected different outcome]
4.2 Common Root Causes
| Category | Common Culprits |
|---|---|
| Null/Undefined | Missing null checks, failed queries |
| Async | Race conditions, missing await |
| Types | Wrong type assumptions, missing casting |
| Scope | Closures, callbacks, this binding |
| State | Stale state, update timing, mutations |
| I/O | Network failures, file not found |
Phase 5: Fix and Verify
5.1 The Fix
Rule #3: Fix the root cause, not the symptom.
## Bug Fix Analysis
SYMPTOM: "user.getFullName is not a function"
WRONG FIX:
user.getFullName?.() // Masks the real problem
RIGHT FIX:
Understand WHY user is undefined
Fix THAT
Then user.getFullName() works naturally
5.2 Verification Protocol
┌─────────────────────────────────────────────────────────────┐
│ FIX VERIFICATION │
│ │
│ 1. Does the original bug still occur? (NO should be answer)│
│ 2. Do existing tests still pass? │
│ 3. Did I introduce any new bugs? │
│ 4. Is the fix minimal? (No over-engineering) │
│ 5. Can I explain the fix in one sentence? │
│ │
│ If all YES → Proceed │
│ If any NO → Revert and reconsider │
└─────────────────────────────────────────────────────────────┘
5.3 Regression Prevention
## Regression Checklist
□ Write a test that fails with the bug
□ Apply the fix
□ Verify the test passes
□ Run full test suite
□ Test related functionality manually
□ Consider edge cases
□ Document the fix
The Debug Session Protocol
Step-by-Step Workflow
┌─────────────────────────────────────────────────────────────┐
│ DEBUG SESSION WORKFLOW │
│ │
│ 1. REPRODUCE │
│ └─► Gather exact error message │
│ └─► List exact steps to reproduce │
│ └─► Create minimal reproduction case │
│ │
│ 2. UNDERSTAND │
│ └─► Parse the error message │
│ └─► Read the stack trace │
│ └─► Identify WHERE the error occurs │
│ │
│ 3. TRACE │
│ └─► Follow data flow backward │
│ └─► Identify potential failure points │
│ └─► Set strategic breakpoints │
│ │
│ 4. HYPOTHESIZE │
│ └─► Form specific hypothesis │
│ └─► Identify how to verify │
│ └─► Test the hypothesis │
│ │
│ 5. FIX │
│ └─► Fix root cause, not symptoms │
│ └─► Keep fix minimal │
│ └─► Write regression test │
│ │
│ 6. VERIFY │
│ └─► Original bug is fixed │
│ └─► No new bugs introduced │
│ └─► All tests pass │
└─────────────────────────────────────────────────────────────┘
Common Debugging Scenarios
Scenario 1: "TypeError: Cannot read property 'x' of undefined"
Analysis:
1. The object 'x' is being accessed on is undefined
2. Either it was never set, or set to undefined
3. Need to trace where it should have been assigned
Steps:
1. Check where object should be created
2. Add breakpoint or log there
3. Verify object exists
4. If not, trace back further
5. Find where it should come from
6. Check why it's not being passed/returned
Scenario 2: "Race condition — sometimes works, sometimes doesn't"
Analysis:
1. Non-deterministic behavior suggests timing issue
2. Usually async-related
Steps:
1. Identify async operations in the flow
2. Check for missing await
3. Check for state updates after async calls
4. Add logging at each async step
5. Reproduce consistently by adding delays
6. Fix the timing issue (usually proper await or reordering)
Scenario 3: "It's not working, no error message"
Analysis:
1. Silent failure is harder to debug
2. Usually caught in try/catch or returning wrong value
Steps:
1. Check for try/catch that swallows errors
2. Add explicit error logging
3. Check return values for error indicators
4. Add console.log at key points
5. Verify function is actually being called
6. Check for early returns
Debugging Anti-Patterns
1. Shooting in the Dark
// BAD: Random changes
const x = result?.data?.value ?? "default";
const y = result?.data?.value || "default";
const z = result && result.data && result.data.value;
// GOOD: Understand why x is undefined
if (!result?.data?.value) {
console.log("result:", result); // NOW you can see
console.log("result.data:", result?.data);
}
2. Premature Optimization
// BAD: "Maybe if I cache it..."
cache.set(key, computeExpensiveValue());
// GOOD: First reproduce, understand, THEN optimize
console.log("Computing for:", input); // Understand first
3. Ignoring the Stack Trace
// BAD: "I have no idea why this error happens"
TypeError at line 45
// GOOD: Read it!
// "Error at getFullName called from UserController line 89"
4. Not Testing the Fix
// BAD: "It seems to work now"
const result = fix();
if (result) console.log("Fixed!");
// GOOD: Write a test
it("should handle empty user gracefully", () => {
const result = processUser(undefined);
expect(result).toEqual({ error: "No user provided" });
});
Key Principles
1. Reproduce Before Fix
If you can't make it fail reliably, you can't know if you fixed it.
2. One Variable at a Time
Change one thing, test, repeat. Multiple changes = confusing results.
3. Rubber Duck Debugging
Explain the problem out loud. The act of explaining forces clarity.
4. Trust the Evidence
Not your intuition, not your assumptions — the actual evidence from the code.
5. When Stuck, Go to the Source
Read the framework/library source. The bug is almost never there, but understanding leads to answers.
Relationship to Other Skills
debug-expert— Core debugging methodologyreproduce-bug— Bug reproduction frameworkunderstand-error— Error message interpretationtrace-execution— Execution path trackingtest-think— Writing regression tests after fixsafe-refactor— If fix requires structural changes
04 同仓库更多 Skills
meeting-minutes
Generate concise, actionable meeting minutes for internal meetings. Includes metadata, attendees, agenda, decisions, action items (owner + due date), and follow-up steps.
documentation-writer
Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.
doc-coauthoring
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
code-review-workflow
Executes comprehensive 4-phase code review: basic review, quality check, bundle analysis, and test coverage. Should be used when the user mentions comprehensive code review, checking code quality, or reviewing staged changes with multi-phase analysis. This is the comprehensive review workflow, distinct from focused skills like frontend-code-review, staged-code-review, or code-change-test-designer.
code-change-test-designer
Analyzes code changes and designs comprehensive test cases. Reads diffs, summarizes capability changes, and designs test cases covering main flows and edge cases. Should be used when the user mentions test coverage, designing tests for code changes, or analyzing diff/commit for testing purposes. Distinguished from code-review-workflow which provides comprehensive review, this skill focuses on test case design for code changes.
skill-creator
Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.