SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsverify-workflow-debug

verify-workflow-debug

Testing & quality

View repository

Updated 10-16 09:45

About this skill

Debug — Systematic Debugging

Entry/Exit

  • Entry: Bug report, test failure, unexpected behavior, performance issue, build failure
  • Exit: Reproduction test passes + docs/bugs/<name>/01-root-cause.md(root cause record)
  • Points to: Return to the original workflow (rebuild or review)
  • Prerequisite loading: CANON.md + build-quality-tdd/SKILL.md
  • Output path: docs/bugs/<name>/01-root-cause.md → build-workflow-execute (rebuild) or verify-workflow-review (re-review)

When not to use

  • Known behavior that does not need fixing (documented limitations, expected behavior)
  • Environment issues that can be resolved by a simple retry (network blip, service restart)

Iron Law

Process: 4 phases must be in order

Phase 1: Root cause investigation

Before attempting any fix:

  1. Read the error message carefully — do not skip the error. Read the full stack trace. Note the line numbers, file paths, and error codes.

  2. Stable reproduction — can it be triggered reliably? What are the exact steps? Does it happen every time? Not reproducible → collect more data, do not guess.

  3. Build a minimal reproduction — remove irrelevant code/config until only the bug itself remains. Simplify the input to the smallest triggering case. A minimal reproduction makes the root cause obvious and prevents fixing the symptom instead of the cause.

  4. Check recent changes — git diff, recent commits, new dependencies, configuration changes, environment differences.

  5. Add diagnostic instrumentation to multi-component systems — when the system spans multiple components (CI → build → signing, API → service → DB):

    • For each component boundary: log what enters the component and what leaves the component
    • Verify environment/configuration propagation
    • Collect evidence in one run showing where it breaks
    • Then analyze the evidence → locate the failing component → investigate that component specifically

  6. Trace the data flow upward — when the error is deep in the call stack: trace upward from the final error point. Where did the erroneous value come from? Who called this with the erroneous value? Keep tracing until you find the source. Fix at the source, not at the symptom.

Phase 2: Pattern analysis

Only fix after determining the pattern:

  1. Find working examples — where is similar working code in the same codebase?
  2. Compare with the reference implementation — when implementing by pattern, read the reference implementation in full. Do not skim.
  3. Identify differences — what is different between what works and what doesn't? List every difference. "This doesn't matter"? This is the most common trap.
  4. Understand dependencies — what components are needed? What settings/configuration/environment? What assumptions does it make?

Phase 3: Hypothesis and verification

  1. Form a single hypothesis — write it down: "I think X is the root cause because Y". Be specific, not vague.
  2. Minimize the test — make the smallest change to test the hypothesis. Change only one variable at a time.
  3. Verify it passes before continuing — Confirmed? → Phase 4. Not confirmed? → New hypothesis. Don't stack more fixes.
  4. When you don't know, say you don't know — "I don't understand X". Don't pretend to know. Seek help. Research more.

Phase 4: Fix

  1. Create reproduction test (RED) — Call build-quality-tdd/SKILL.md to write a failing test. Test first, then fix.A fix without a reproduction test = no fix.
  2. Implement a single fix — Address the identified root cause. One change at a time. No "while I'm at it" changes.
  3. Verify the fix (GREEN) — Does the test pass? Are other tests unaffected? Is the problem actually solved?
  4. If the fix doesn't work — STOP. Count how many attempts were made.
    • < 3 attempts: Go back to Phase 1 and re-analyze with new information
    • ≥ 3 attempts: Freeze. Enter Phase 4.5

Phase 4.5: Architecture Challenge Gate

3 consecutive failed fixes = architecture problem:

Signs:

  • Each fix exposes new problems in shared state/coupling/different locations
  • The fix requires a "large-scale refactor" to be implemented
  • Each fix causes new symptoms elsewhere

STOP and question the foundation:

  • Does this pattern hold fundamentally?
  • Are we sticking with it "out of inertia"?
  • Refactor the architecture vs. continue fixing symptoms?

Discuss with a human before attempting more fixes. This is not a failed hypothesis — this is the wrong architecture.

Error Type-Specific Diagnosis

Test failure

测试在代码变更后失败：
├── 代码被测试覆盖了？
│   └── YES → 测试还是代码错了？
│       ├── 测试过时 → 更新测试
│       └── 代码有 bug → 修复代码
├── 改了不相关的代码？
│   └── YES → 副作用 → 检查共享状态、import、全局变量
└── 测试本来就 flaky？
    └── 检查时序问题、顺序依赖、外部依赖

Build failure

构建失败：
├── 类型错误 → 读错误信息，检查对应位置类型
├── Import 错误 → 模块存在？exports 匹配？路径正确？
├── 配置错误 → 检查构建配置文件的语法/schema
├── 依赖错误 → 检查 package.json，重装依赖
└── 环境错误 → Node 版本、OS 兼容性

Runtime error

运行时错误：
├── TypeError: Cannot read property 'x' of undefined
│   └── 某个值不该 null/undefined → 向上追溯数据流
├── 网络错误 / CORS
│   └── 检查 URL、headers、服务端 CORS 配置
├── 渲染错误 / 白屏
│   └── 检查 error boundary、console、组件树
└── 意外行为（无错误）
    └── 关键路径加日志，验证每一步数据

Safe Fallback Pattern

Under time pressure, use safe degradation, don't crash:

// 安全默认 + 警告（不崩溃）
function getConfig(key: string): string {
  const value = process.env[key];
  if (!value) {
    console.warn(`Missing config: ${key}, using default`);
    return DEFAULTS[key] ?? '';
  }
  return value;
}

// 优雅降级（不展示破碎功能）
function renderChart(data: ChartData[]) {
  if (data.length === 0) {
    return <EmptyState message="暂无数据" />;
  }
  try {
    return <Chart data={data} />;
  } catch (error) {
    console.error('Chart render failed:', error);
    return <ErrorBoundaryFallback />;
  }
}

Good and Bad Examples

Good — Systematic root cause + fix verification

Phase 1 Read the error message + stable reproduction + minimal reproduction → Phase 2 Find a working example and compare the differences → Phase 3 Hypothesize "N+1 query is the root cause" → Phase 4 Write reproduction test (RED) → Fix → Test passes (GREEN). Root cause is traceable, fix is verifiable.

Bad — Random trial and error

"Try changing this", "change that too", "change three places and run together". No reading the error message, no reproduction steps, no single hypothesis, no reproduction test. Fixed the symptom without knowing the root cause; the same type of bug recurs in other locations.

Output Templates

  • Phase 1-3 use templates/bug/01-root-cause.md, write to disk at docs/bugs/<name>/01-root-cause.md
  • Phase 4 use templates/bug/02-fix-plan.md, write to disk at docs/bugs/<name>/02-fix-plan.md

The root cause record must include: Status Summary, symptoms, impact scope, timeline, reproduction steps, reproduction evidence, investigation process, root cause, non-root-cause exclusions, fix direction, Done When.

The fix plan must include: Status Summary, fix goal, minimal change scope, reproduction test, fix steps, verification plan, regression risk, Follow-up Actions, Done When.

Related Skills

  • Write reproduction test → build-quality-tdd/SKILL.md
  • Verify fix → CANON Rule 5 (Verify Don't Assume)

Verification Evidence

The output or record must include:

  • Input/Source: the spec, plan, code, feedback, or release context that was read.
  • Actions Performed: Actual completed inspection, generation, fix, export, or release steps.
  • Verification results: Commands, review conclusions, artifact paths, screenshots, or manual confirmation.
  • Blockers/Rollback: Failed items, rollback paths, or issues requiring a human partner decision.

Common sayings

Saying Reality Consequence
"Quick fix, investigate later" There is no later. Root cause first, then fix. Fixing symptoms instead of root causes makes the same type of bug recur in 3 different places, and the cumulative fix time is 10x that of a single root cause investigation.
"Let's just change it and see if it works" Guessing. Determine the root cause first. Guess-based debugging wastes an average of 45 minutes (industry data), while systematic debugging averages 15 minutes. Every wrong guess obscures a real clue.
"Change multiple places and run it once" Cannot isolate the effective change. Two changes interfere with each other, and passing is purely coincidental. The next time only one of them is changed, the failure reproduces, and it is impossible to determine which change "really" fixed the problem.
"Skip tests, verify manually" Manual testing cannot prove edge cases. Edge conditions missed by manual verification (concurrency, null values, timeouts) appear as intermittent production failures, and troubleshooting takes 2-8 hours.
"Emergency, no time for process" Systematic debugging is faster than guessing. The probability that guess-based fixes during an emergency introduce new bugs is ~40%, and the downtime loss from a secondary incident is greater than the extra 10 minutes spent on systematic debugging.
"Just try again" (3rd+ time) 3 failures = architecture problem. Question it; do not keep guessing. The 4th, 5th, and 6th attempts will not be better than the first 3. Each failure introduces more uncertainty, and eventually everything has to be rolled back, wasting time and making the code messier.

Violating the letter of the rule is violating the spirit. There is no gray area.

Verification failure handling

Failure scenario Handling method
Cannot reproduce the bug Collect more data (logs, monitoring, user context); do not guess. Non-reproducible = cannot confirm the fix
Tests still fail after the fix STOP. Count the number of attempts. < 3 times → return to Phase 1 for re-analysis; ≥ 3 times → enter the Phase 4.5 architecture questioning gate
Fix introduces a regression Roll back the fix and re-analyze the root cause and side effects
Cannot find a working reference example Expand the search scope to other projects using the same tech stack, or seek human guidance
The reproduction test itself is flawed Fix the test and ensure the RED→GREEN cycle is effective. Do not fix the code before the test is correct

Red flag — STOP and follow the process

All means: STOP. Return to Phase 1.

Pay attention to signals from your human partner:

  • "Did it maybe not happen?" — you assumed but did not verify
  • "Can you... take a look?" — you add diagnostic evidence
  • "Stop guessing" — you proposed a fix without understanding the root cause
  • "Are we stuck again?" (frustrated) — Your approach is wrong

All of this means: STOP. Go back to Phase 1.

Verification Checklist

  • Root cause identified (not a guess)
  • Error message fully read and understood
  • Has stable reproduction steps
  • Wrote a pair of reproduction tests (RED→GREEN verification)
  • Fix targets the root cause, not the symptom
  • All tests pass + no regressions
  • Root cause record saved to docs/bugs/<name>/01-root-cause.md
  • Fix plan saved to docs/bugs/<name>/02-fix-plan.md