oimiragieo
oimiragieo/agent-studio
相关职业SOC
基于 SOC 职业分类
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/oimiragieo/agent-studio --skill debugging命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Agent frontmatter enhancements — disallowedTools, mcpServers scoping, fork_eligible field
Context management — pre-compact persistence, threshold alignment, microcompact/circuit breaker detection
Hook enhancements — updatedInput for bash safety prefixes, suppressOutput for verbose blocks, denial-based routing feedback
正在显示 SKILL.md
基于 SOC 职业分类
| name | debugging |
| description | Systematic 4-phase debugging with root cause investigation. Use when fixing bugs to prevent random fixes. |
| version | 1.1.1 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Write","Edit","Bash","Glob","Grep"] |
| best_practices | ["Investigate root cause before any fix","Reproduce the bug reliably first","Compare working vs broken examples","Make one change at a time"] |
| error_handling | strict |
| streaming | supported |
| verified | true |
| lastVerifiedAt | "2026-02-22T00:00:00.000Z" |
| source | builtin |
| trust_score | 100 |
| provenance_sha | c4c30b4297adcffa |
Mode: Cognitive/Prompt-Driven — No standalone utility script; use via agent context.
Random fixes waste time and create new bugs. Quick patches mask underlying issues.
Core principle: ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
Violating the letter of this process is violating the spirit of debugging.
Use for ANY technical issue:
Use this ESPECIALLY when:
Don't skip when:
| Scenario | Use debugging | Use smart-debug |
|---|---|---|
| Simple, locally reproducible bug | Yes | Overkill |
| Root cause area already known |
| Yes |
| Optional |
| Static analysis / code review bug | Yes | No |
| Runtime / production issue | Start here | Preferred |
| Intermittent / hard-to-reproduce | Escalate | Yes |
| Needs hypothesis ranking gate | No | Yes (blocking) |
| Needs instrumentation + log analysis | No | Yes |
| Observability-driven (traces, APM) | No | Yes |
Rule of thumb: Start with debugging for straightforward bugs. Escalate to smart-debug when you need hypothesis ranking, structured instrumentation, or the bug is intermittent/production-only.
See also: .claude/skills/smart-debug/SKILL.md
You MUST complete each phase before proceeding to the next.
BEFORE attempting ANY fix:
Read Error Messages Carefully
Reproduce Consistently
Check Recent Changes
Gather Evidence in Multi-Component Systems
WHEN system has multiple components (CI - build - signing, API - service - database):
BEFORE proposing fixes, add diagnostic instrumentation:
For EACH component boundary:
- Log what data enters component
- Log what data exits component
- Verify environment/config propagation
- Check state at each layer
Run once to gather evidence showing WHERE it breaks
THEN analyze evidence to identify failing component
THEN investigate that specific component
Example (multi-layer system):
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# Layer 4: Actual signing
codesign --sign "$IDENTITY" --verbose=4 "$APP"
This reveals: Which layer fails (secrets - workflow OK, workflow - build FAIL)
For distributed/microservice systems — prefer OpenTelemetry traces:
# Query traces by component (preferred over manual echo/env logging)
pnpm trace:query --component <service-name> --event <event-name> --since <ISO-8601> --limit 200
# When trace ID is already known
pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200
Fragmented traces (each service has its own root span, trace IDs don't match across boundaries)
= broken context propagation. Fix traceparent/tracestate header forwarding before investigating business logic.
Instrumentation Gate (before hypothesis generation): If runtime behavior remains unclear after static analysis, add targeted log statements at key decision nodes before generating hypotheses. Use session-scoped log files (
.claude/context/tmp/debug-{sessionId}.log) to capture runtime state. Human-in-the-loop: ask the user to reproduce the bug after instrumentation is added, before analyzing results. Only proceed to Phase 2 once runtime evidence is collected.
Trace Data Flow
WHEN error is deep in call stack:
See root-cause-tracing.md in this directory for the complete backward tracing technique.
Quick version:
Find the pattern before fixing:
Find Working Examples
Compare Against References
Identify Differences
Understand Dependencies
Scientific method:
Form Single Hypothesis
Test Minimally
Verify Before Continuing
When You Don't Know
Fix the root cause, not the symptom:
Create Failing Test Case
tdd skill for writing proper failing testsImplement Single Fix
Verify Fix
Cleanup
rg "debug-{sessionId}" --type-add 'src:*.{js,ts,cjs,mjs}' -tsrc .If Fix Doesn't Work
If 3+ Fixes Failed: Question Architecture
Pattern indicating architectural problem:
STOP and question fundamentals:
Discuss with your human partner before attempting more fixes
This is NOT a failed hypothesis - this is a wrong architecture.
If you catch yourself thinking:
ALL of these mean: STOP. Return to Phase 1.
If 3+ fixes failed: Question the architecture (see Phase 4.5)
Watch for these redirections:
When you see these: STOP. Return to Phase 1.
| Excuse | Reality |
|---|---|
| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
| "I see the problem, let me fix it" | Seeing symptoms does not equal understanding root cause. |
| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
| Phase | Key Activities | Success Criteria |
|---|---|---|
| 1. Root Cause | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
| 2. Pattern | Find working examples, compare | Identify differences |
| 3. Hypothesis | Form theory, test minimally | Confirmed or new hypothesis |
| 4. Implementation | Create test, fix, verify | Bug resolved, tests pass |
If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
But: 95% of "no root cause" cases are incomplete investigation.
These techniques are part of systematic debugging and available in this directory:
root-cause-tracing.md - Trace bugs backward through call stack to find original triggerdefense-in-depth.md - Add validation at multiple layers after finding root causecondition-based-waiting.md - Replace arbitrary timeouts with condition polling.claude/tools/analysis/find-polluter/find-polluter.sh (or find-polluter.ps1 on Windows) from the project root to isolate which test pollutes the suite.Related skills:
From debugging sessions:
For distributed systems, OpenTelemetry traces replace manual echo/env evidence gathering. A trace shows the complete request journey across service boundaries via span IDs and trace IDs (W3C Trace Context standard: traceparent/tracestate headers).
Evidence hierarchy for distributed failures (prefer in order):
1. Distributed traces (OpenTelemetry spans, correlated trace IDs)
2. Structured logs with correlation IDs
3. Metrics with timestamps
4. Manual instrumentation (Phase 1 Step 4 bash examples)
Common symptom — fragmented traces: Each service shows its own root span, trace IDs don't match across boundaries. This means context propagation is broken — fix header forwarding before investigating business logic.
LLM-based debugging agents (2025 pattern) augment Phase 1 by reading production traces and correlating with codebase context to suggest minimal reproduction cases.
Use AI assistance for:
Do NOT skip Phase 1 when using AI assistance. AI suggestions are hypotheses — apply Phase 3 (hypothesis testing) before implementing any AI-suggested fix. AI cannot replace systematic investigation; it accelerates evidence gathering.
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| "Quick fix for now, investigate later" | The quick fix becomes permanent; the root cause resurfaces as a different symptom | Always complete Phase 1 before touching production code |
| Making multiple changes at once | Can't determine which change fixed or broke the system; creates regressions | One change per hypothesis test; verify before the next change |
| Proposing AI-suggested fixes without testing | AI suggestions are hypotheses, not facts; applying them blindly skips Phase 3 | Treat AI suggestions as hypotheses to test, not answers to implement |
| Attempting a 4th fix after 3 failures | N+1 fix attempts on a broken approach compound the problem | After 3 failed fixes, escalate to architecture review |
| Skipping the failing test before the fix | You can't verify the fix worked, and regressions are invisible | Create the failing test first; it proves root cause and verifies fix |
Before starting:
Read .claude/context/memory/learnings.md
After completing:
.claude/context/memory/learnings.md.claude/context/memory/issues.md.claude/context/memory/decisions.mdASSUME INTERRUPTION: If it's not in memory, it didn't happen.