Agent Skills
› AjayIrkal23/agentic-mercy-10x
› debug-investigation
debug-investigation
GitHub用于在未知Bug根因时进行系统化调试。通过复现、最小化、假设和仪器检测四阶段定位问题，并依据前后端或跨层故障面加载对应合规标准技能集，确保证据充分后再提出修复方案。
Trigger Scenarios
Bug或回归原因不明
需要证据以选择修复方案
出现崩溃或意外行为
Install
npx skills add AjayIrkal23/agentic-mercy-10x --skill debug-investigation -g -y
SKILL.md
Frontmatter
{
"name": "debug-investigation",
"schema": 1,
"category": "debug",
"surfaces": [
"backend",
"frontend"
],
"triggers": {
"paths": [
".claude\/hooks\/",
".claude\/rules\/"
],
"intents": [
"debug"
],
"keywords": [
"approach",
"behavior",
"break",
"broken\/throwing\/failing",
"bug",
"bugs",
"builds",
"cause",
"crash",
"debug",
"debugging",
"describes",
"diagnose",
"diagnosis",
"disciplined",
"doesn",
"encounter",
"error",
"evidence",
"expectations",
"fail",
"failures",
"finding",
"fix",
"fixing",
"guessing",
"guides",
"hard",
"hypothesise",
"instrument",
"investigation",
"isolate",
"issue",
"loop",
"match",
"minimise",
"need",
"needed",
"performance",
"proposing",
"rather",
"regression",
"regression-test",
"regressions",
"reports",
"reproduce",
"root",
"root-cause",
"says",
"something",
"systematic",
"tests",
"unexpected",
"unknown",
"user"
]
},
"platforms": [
"linux",
"darwin",
"windows"
],
"token-cost": 860,
"description": "ALWAYS invoke when the cause of a bug, regression, crash, or unexpected behavior is unknown and evidence is needed before proposing a fix.",
"disable-model-invocation": false
}
Debug Investigation
Overview
This is the debugging shell.
It does not assume frontend and backend both matter. It classifies the failing surface first, then uses the matching domain skills to trace the problem.
Use When
- The failure source is unclear.
- A regression, crash, or unexpected behavior needs evidence.
- You need root cause before choosing the fix.
Do Not Use
- Straightforward implementation work.
- Design-first tasks.
- Documentation lookup without an actual failure to investigate.
Surface Selection Rule
Choose the failing surface first:
- Backend-only: load the mandatory Backend Core Compliance Set before forming hypotheses:
backend-standards-always-follow,service-layer-standards,backend-api-standards,backend-error-handling, andbackend-performance-standards. Preserveapi-contract-standardsfor envelope/contract work andscaffold-standardsfor domain or skeleton creation. - Frontend-only: select and load the matching Build Web Apps plugin skill when available, then load the mandatory Frontend Core Compliance Set:
build-web-apps:frontend-app-builderfor visual-surface failures orbuild-web-apps:react-best-practicesfor React/Vite/UI/code failures, plusfrontend-standards-always-follow,frontend-structure-standards,frontend-response-handling,frontend-server-data-patterns,frontend-api-standards, andreact-hooks-patterns. - Cross-surface: load the matching Build Web Apps plugin plus Frontend Core Compliance Set and Backend Core Compliance Set, then narrow to the actual failing handoff.
Use project-reference-linkage when tracing linked layers.
Use mcp-usage-standards when repo, DB, logs, or external system truth must be verified.
Workflow
Phase 1 — Reproduce
- Confirm the bug is reproducible in a minimal isolated case.
- Write a failing test or script that demonstrates the defect before touching any source code.
- Record the exact input, environment, and output that causes the failure.
- Verify the reproduction is deterministic (fails every time, not flakily).
Phase 2 — Minimise
- Strip the reproduction case to the smallest set of files, inputs, and dependencies.
- Remove unrelated code paths, environment noise, and network dependencies.
- If the minimal case no longer fails, add back pieces until it fails again — that is the root cause scope.
Phase 3 — Hypothesise
- List all plausible root causes (do not commit to one yet).
- Order by likelihood based on evidence: recent changes, error messages, stack traces, logs.
- For each hypothesis, define a concrete observable that would confirm or refute it.
- Do not fix anything yet — hypothesis must precede instrumentation.
Phase 4 — Instrument
- Add targeted logging or assertions to the narrowed scope — no broad logging.
- Run the minimal reproduction case with instrumentation.
- Observe which hypothesis the evidence supports.
- If no hypothesis is confirmed, add one more instrument and repeat from Phase 3.
- Once root cause confirmed: implement the fix in the narrowest scope possible, run the reproduction test (it must now pass), then run the full test suite.
Output Contract
- Failure summary.
- Touched surfaces and trace path.
- Evidence-backed root cause or smallest suspect area.
- Minimal safe fix.
- Verification steps.
References
- Use
references/full-guide.mdif you need the previous full strict guide.
Version History
- 581d130 Current 2026-07-19 09:06
