1.5k first-fluke

oma-debug Skill

诊断可复现的故障,修复根因并验证回归。用于崩溃、错误行为和失败的测试。

安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。

查看源码

技能指令原文(SKILL.md)

Debug Agent - Bug Fixing Specialist

Scheduling

Goal

Reproduce, diagnose, minimally fix, and regression-test bugs while preserving scope discipline and documenting root cause.

Intent signature

  • User reports a bug, crash, traceback, exception, error message, performance issue, intermittent failure, or regression.
  • User needs root cause analysis plus a minimal code fix and regression test.

When to use

  • User reports a bug with error messages
  • Something is broken and needs fixing
  • Performance issues or slowdowns
  • Intermittent failures or race conditions
  • Regression bugs

When NOT to use

  • Building new features -> use Frontend/Backend/Mobile agents
  • General code review -> use QA Agent

Expected inputs

  • Error message, failing behavior, reproduction steps, logs, test failure, or affected code path
  • Existing tests, stack traces, environment notes, and suspected regression boundary

Expected outputs

  • Root cause explanation
  • Minimal fix scoped to the failing behavior
  • Regression test or explicit reason it cannot be added
  • Bug documentation under .agents/results/bugs/ when appropriate

Dependencies

  • resources/execution-protocol.md, resources/checklist.md, and resources/debugging-checklist.md
  • Local codebase search and symbol/reference tools
  • Project test, lint, typecheck, and runtime commands

Control-flow features

  • Branches by reproduction success, error class, suspected layer, and verification outcome
  • Reads logs/code/tests and writes code/tests/docs
  • Must search for similar patterns after fixing

Structural Flow

Entry

  1. Capture the reported symptom and suspected scope.
  2. Reproduce or establish the closest reliable failing signal.
  3. Identify affected files, tests, and related patterns.

Scenes

  1. PREPARE: Gather symptoms, logs, reproduction path, and verification command.
  2. ACQUIRE: Read failing code, tests, references, and similar patterns.
  3. REASON: Isolate root cause and reject unsupported hypotheses.
  4. ACT: Apply minimal fix and regression test.
  5. VERIFY: Re-run the original failing check and the regression test. Run broader suites only when the user or the active workflow requires it; otherwise report them as not run.
  6. FINALIZE: Document root cause, fix, test, and residual risk.

Transitions

  • If reproduction fails, use logs/tests to establish a weaker but explicit diagnostic signal.
  • If the first fix fails verification, return to root-cause analysis.
  • If similar patterns exist, inspect and patch only affected cases.
  • If the request is actually feature work, route to the relevant implementation skill.

Failure and recovery

  • If environment is missing, document the blocker and provide the closest static diagnosis.
  • If no regression test is feasible, explain why and include manual verification.
  • If fix scope grows, stop and call out the broader design issue.

Exit

  • Success: bug is fixed, regression coverage exists, and the original failing check and regression test pass.
  • Partial success: root cause or verification blocker is explicit.

Logical Operations

Actions

| Action | SSL primitive | Evidence |
|--------|---------------|----------|
| Reproduce failure | CALL_TOOL | Test/runtime/log command |
| Search affected code | READ | Code, tests, symbols, references |
| Compare similar patterns | COMPARE | Pattern search |
| Infer root cause | INFER | Diagnostic reasoning |
| Write minimal fix | WRITE | Code patch |
| Write regression test | WRITE | Test patch |
| Verify behavior | VALIDATE | Failing check and regression test |
| Report result | NOTIFY | Root-cause summary |

Tools and instruments

  • Project test, lint, typecheck, runtime, and logging commands
  • Configured code-intelligence symbol/reference/pattern search with native fallback
  • Bug report templates and the tools reference in resources/debugging-checklist.md

Canonical workflow path

Use the configured code-intelligence provider to locate files and inspect symbols
or content. For Serena, use find_file, search_for_pattern,
get_symbols_overview, and find_symbol. Native search is limited to the
provider exclusions and non-code paths permitted by the project's search policy.

Then run the smallest reproduction command first, establish the causal mechanism, and follow resources/execution-protocol.md for the diagnosis record when an OMA workflow is active. Add the regression test and re-run it with the original failing check (RED before the fix, GREEN after). Run broader suites only when the user or the active workflow requires it; otherwise report them as not run.

Resource scope

| Scope | Resource target |
|-------|-----------------|
| CODEBASE | Failing source, tests, and related patterns |
| LOCAL_FS | Bug reports and result artifacts |
| PROCESS | Reproduction and verification commands |
| MEMORY | Hypotheses, root-cause notes, verification evidence |

Preconditions

  • A bug signal, symptom, or failing behavior is available.
  • Relevant code and verification path can be inspected or the blocker is stated.

Effects and side effects

  • Mutates source/tests only as needed for the fix.
  • May create bug documentation under .agents/results/bugs/.

Guardrails

  1. Reproduce first, then diagnose - never guess at fixes
  2. Identify root cause, not just symptoms
  3. Minimal fix: change only what's necessary
  4. Every fix gets a regression test
  5. Search for similar patterns elsewhere after fixing
  6. Document in .agents/results/bugs/

Code intelligence

Use the configured provider to locate the failing function, find callers, and search similar error patterns. Native search and scoped reads are supported fallbacks; see the shared capability contract.

References

  • Local code tools: ../_shared/core/code-intelligence.md (code search/navigation)
  • Execution steps (follow for the selected task): resources/execution-protocol.md
  • Checklist (pre-submit self-verification): resources/checklist.md
  • Error recovery: resources/error-playbook.md
  • Bug report template (Complex or CRITICAL/HIGH bugs): resources/bug-report-template.md
  • Condensed bug report, tools reference, and handoff routing: resources/debugging-checklist.md
  • Context loading: ../_shared/core/context-loading.md
  • Context budget: ../_shared/core/context-budget.md
  • Lessons learned: ../_shared/core/lessons-learned.md (matching prior failure or requested retrospective)
  • Observability handoff: ../oma-observability/SKILL.md §Integrations — traces/logs by trace_id, 6-dim forensics

配合站内内容