goat-debug
Use when diagnosing a bug, unexpected behaviour, system failure, or unfamiliar code that needs structured investigation.
blundergoat · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add blundergoat/goat-flow --skill goat-debug技能说明
name: goat-debug description: "Use when diagnosing a bug, unexpected behaviour, system failure, or unfamiliar code that needs structured investigation." goat-flow-skill-version: "1.18.0"
/goat-debug
Shared Conventions
Read .goat-flow/skill-docs/skill-preamble.md for shared conventions.
On full-depth, also read .goat-flow/skill-docs/skill-conventions.md.
When to Use
Use when diagnosing a bug or understanding unfamiliar code. For onboarding, use investigate mode.
- Bug/symptom --> Diagnose mode. Exploring, no bug --> Investigate mode. Already-applied fix --> Step 0 verification.
If you want to "just try something" before tracing the code path, STOP. That is the failure mode this skill exists to prevent.
| Excuse | Reality |
|---|---|
| "The user already diagnosed it, hypotheses are ceremony" | A confidently stated cause is data, not diagnosis. Trace it or eliminate it before acting. |
| "Prod is on fire, D1 is a luxury" | Untraced fixes at 2am are how you get a 3-fix abort at 4am. D1 is the shortest path to a working fix. |
| "Type/config mismatch is a really clean story" | Clean stories that don't mechanically match the symptom (e.g. value-dependent failure from a value-blind cause) are wrong stories. |
| "The specific number in the bug report is probably just phrasing" | Treat every specific number, threshold, or boundary in a bug report as a clue, not rhetoric. |
| "Reading the footgun during an incident looks like second-guessing" | Reading the footgun IS doing your job. Not reading it is what looks bad at post-mortem. |
| "Adding the field is zero-risk - worst case we try the next thing" | This is how you enter the 3-fix abort loop. Hypothesis before code, always. |
Boundary Commands
- NEVER: Turn diagnosis into review, test planning, milestone planning, or an ungated fix.
- ALWAYS in Diagnose mode: Trace the live path, test competing hypothesis categories, and state the reproduction and evidence limits.
- DEFER TO:
/goat-reviewfor quality,/goat-qafor test plans,/goat-planfor milestones, and the dispatcher for feature briefs.
Step 0 - Choose Depth
Already-applied change: existing-fix verification. Identify change, environment/state, original failing steps, expected result, earlier evidence, and execution authority; historical proof is context. Go directly to D4 without D2/D3, hypotheses, minimisation, or causal confidence. Use the reference's verification report; diagnosis-only obligations apply only if diagnosis runs.
New diagnosis: Valid explicit depth wins within governing policy. Otherwise Full risk/scope triggers override Quick defaults:
- Quick: isolated 1-2 files, diagnosis only, or supplied reproduction; bounded primary-path investigation and compact report.
- Full: cross-component, no reproduction, CI/prod/user-visible impact, or possible fix; trace implicated component boundaries and relevant runtime/configuration context. If uncertain, choose Full. If vague, ask about: goal, symptom/error message, area involved, and what was already tried with its outcome; prior attempts enter D1 as evidence to trace, not as eliminated hypotheses.
Both diagnosis depths: D1 + applicable D1.5 + D2; read primary file, test 2 hypothesis categories, attempt reproduction or state gap. Before D2, run D1.5 or state reproduction already minimal, reduction not applicable, or unsafe to reduce with literal input/command and reason. Quick never enters D3 or D4 directly.
Full is gated, not linear: run D1 through D2, then stop, investigate deeper, or request a fix plan. Full diagnosis-only may stop at D2. If a Quick diagnosis leads to a fix request, promote to Full at the D2 gate; do not skip either approval. D3 planning follows the first approval; implementation requires the separate D3 approval; D4 follows implementation only.
Footgun check: Use the preamble's learning-loop retrieval on .goat-flow/learning-loop/footguns/ and .goat-flow/learning-loop/lessons/ for the target area. Surface matches or an explicit retrieval miss; do not broad-load either bucket.
Browser evidence detection: URL, local page, screenshot, rendering, or browser console/network symptoms require .goat-flow/skill-docs/playbooks/browser-use.md; it owns availability, installation approval, and manual fallback.
For Diagnose/existing-fix modes, read references/diagnostic-techniques.md only for ranking-matrix detail, mutation classification, reduction-method selection, causal-distinction detail, worked diagnosis, or existing-fix reporting.
Diagnose Mode
D1 - Investigate (no fixes)
After reading the primary file (the first relevant file at the entry or failure boundary, not a file named by chance), declare a scope snapshot: symptom boundary (what is failing), affected components (files/modules/services involved), read estimate, and decision-relevant source/runtime/configuration state as the baseline. Drift is material when it touches an affected component or the reproduction; record it without persisting secrets or raw sensitive values.
Write 2-3 hypotheses spanning at least 2 of: Data, Logic, Timing, Environment, Configuration. If the bug involves loops, indices, or pagination, include a boundary/counting hypothesis.
Hypothesis ranking: Before expensive tracing, reduction, or experiments, rank the hypotheses by likelihood and cost; re-rank whenever evidence changes.
Test cheap-and-likely first; skip expensive-and-unlikely until cheap options are eliminated. When survivors remain, run the cheapest authorized distinguishing check, or cite deterministic proof that entails the symptom; one intervention per hypothesis is never required.
After tracing, mark each: CONFIRMED / ADJUSTED / ELIMINATED / UNRESOLVED with file + semantic anchor evidence.
Multi-component failures: Record each boundary's input, output, and broken invariant; investigate the failing component. New instrumentation fo
阅读完整来源 ↗