Debugging

Debugging

Use this skill when the job is to turn a concrete failure into a bounded diagnosis loop.

The center of the skill is small and repeatable: 1. define the failing behavior in testable terms, 2. build or confirm the cheapest reliable reproducer, 3. isolate the narrowest failing boundary, 4. run one discriminating check per hypothesis, 5. verify the fix under the same conditions.

Read references/handoff-boundaries.md before taking work that may belong to log-analysis, testing-strategies, code-review, or performance-optimization. Read references/debug-loop.md for the full experiment-loop scaffolding. Read references/mode-selection-and-fast-checks.md when the case is clearly a regression, flake, env/config mismatch, or artifact-led investigation.

When to use this skill

• A command, test, request, or UI flow fails and the user needs a root-cause workflow
• A bug is reproducible or close to reproducible and needs narrowing before patching
• A regression has a likely change window or last-known-good state
• A flaky failure needs repeated-run evidence, isolation, and stabilization of one concrete case
• CI/staging/prod-only behavior now has enough evidence to compare environment or config differences
• The user asks how to reproduce, isolate, bisect, confirm, or verify a bug fix

When not to use this skill

• The user only has logs / stack traces and still needs the first actionable failure → use log-analysis
• The real task is test-program design, flake policy, or coverage planning → use testing-strategies
• The task is reviewing a diff / PR for correctness, risk, or missing evidence → use code-review
• The main job is telemetry rollout, dashboards, or observability-platform design → use monitoring-observability
• The main job is bottleneck measurement and optimization tradeoffs → use performance-optimization

Instructions

Step 1: Freeze the failure definition

Write the failure in a form that can be retested.

Capture:

• expected behavior
• actual behavior
• exact trigger, input, or state
• environment: local / CI / staging / production / browser / mobile / runtime
• deterministic vs flaky vs unknown
• last-known-good state if this may be a regression

Minimum shape:

Expected: ...
Actual: ...
Trigger: ...
Environment: ...
Confidence: high | medium | low

If the report is still just "something failed" with giant logs and no narrowed symptom, route to log-analysis first.

Step 2: Choose the right first evidence source

Pick the cheapest path that can falsify or confirm your next hypothesis.

Use this routing shortcut:

• Known failing command/test/request/UI flow → reproduce it directly
• Regression with last-known-good → compare recent changes and consider git bisect
• Flaky / intermittent → measure frequency first with repeated runs
• CI/staging/prod only → compare env/config/runtime facts before speculating about code
• Artifact-led case → inspect the first meaningful log/trace/screenshot, then narrow to one suspect boundary
• Performance-only complaint → route to performance-optimization unless a concrete broken behavior still needs diagnosis

Step 3: Build the smallest reliable reproducer

Prefer the cheapest reproduction that still fails.

Common shapes:

• one CLI command
• one HTTP request or API call
• one UI flow with exact steps
• one failing test or fixture
• one save file / seed / payload / config combination
• one commit range for regression hunting

Useful tactics:

• reduce unrelated setup
• freeze time/randomness/network when possible
• capture exact env/config values that differ
• keep repeated-run loops focused on one suspect

Step 4: Isolate the boundary before proposing fixes

Narrow the problem first.

Isolation angles: 1. boundary — UI vs API vs DB vs worker vs config vs dependency vs asset/runtime 2. input — one payload, record, seed, scene, or fixture 3. history — what changed between good and bad 4. environment — local vs CI vs staging vs production 5. timing — ordering, retries, caching, clocks, async waits, shared state

High-value questions:

• Can one file/module/config branch now be named as the primary suspect?
• Is the failure about data shape, state transition, config drift, dependency behavior, or code path?
• Is the current bottleneck still diagnosis, or has the task shifted to review / test-policy / optimization work?

Step 5: Run one discriminating check per hypothesis

Do not patch five things at once.

For each hypothesis:

• state why it explains the failure
• run one read-only or reversible check first
• record the result
• keep or reject the hypothesis based on evidence

Good first checks:

• inspect the request/payload/config at the narrowed boundary
• compare one good state and one bad state
• rerun one targeted test instead of the whole suite
• diff the suspect commit range
• add temporary instrumentation only at the narrowed boundary

Step 6: Use the right mode packet

Once the case type is clear, follow the matching packet in references/mode-selection-and-fast-checks.md:

• regression debugging
• flaky-failure debugging
• env/config mismatch debugging
• artifact-led debugging after log/trace/screenshot triage
• runtime / browser / game-loop debugging

Step 7: Fix the cause, then prove it

A good debugging result shows that the cause was addressed, not just the symptom muted.

Verification checklist:

• the reproducer now passes
• nearby edge cases still behave correctly
• a regression guard exists when practical
• the explanation matches the observed failure
• the fix scope is smaller than the search space you started with

Step 8: Escalate honestly when evidence is still weak

If reproduction or isolation still fails: 1. say confidence is low, 2. ask for the smallest missing artifact only, 3. avoid pretending the root cause is known, 4. prefer one more discriminating check over speculative patching.

Output format

Always return a concise debugging brief or debugging plan.

# Debugging Brief

## Failure definition
- Expected: ...
- Actual: ...
- Reproducer: ...
- Confidence: high | medium | low

## Isolation result
- Narrowed boundary: ...
- Recent change / env difference / artifact clue: ...

## Hypotheses and checks
1. Hypothesis: ...
   - Check: ...
   - Result: ...

## Likely root cause
- 1-3 sentences grounded in evidence

## Fix direction
1. ...
2. ...

## Verification
- Reproducer rerun: ...
- Regression guard: ...

## Handoff
- Stay in `debugging` | route to `log-analysis` | route to `testing-strategies` | route to `code-review` | route to `performance-optimization`

Examples

Example 1: Regression after a refactor

Input

Saving a profile without uploading a new avatar now clears the existing avatar. It worked before the refactor.

Output sketch

• Define expected vs actual behavior in one reproducible form submission
• Compare the update path before/after the refactor
• Check whether absent field and explicit null are treated the same
• Verify with a focused regression test and rerun of the original flow

Example 2: Flaky CI failure

Input

This checkout test passes locally but fails in CI about one in eight runs.

Output sketch

• Mark the case as flaky, not deterministic
• Run a repeated-run loop and compare timing/shared-state/env differences
• Inspect only the failing test and nearby fixtures first
• Route to testing-strategies only if the job expands into suite-wide flake policy

Example 3: Prod-only behavior with artifact clue

Input

The job only fails in staging. I have the first failing request payload and the config diff.

Output sketch

• Treat this as env/config mismatch debugging
• Compare staging vs local/runtime facts before patching code
• Narrow to the one flag/version/secret branch that changes behavior
• Verify with the same payload under the corrected config

Example 4: Symptom-only log dump

Input

Here are 500 lines of retries and stack traces. Can you debug this?

Output sketch

• Route first to log-analysis
• State that the first actionable failure still needs narrowing
• Do not pretend a root-cause loop can start yet

Best practices

1. Reproduce before patching — unproven fixes are guesses. 2. Use the cheapest evidence source first — direct repro, repeated run, env diff, or artifact clue. 3. Keep mode selection explicit — regression, flake, env/config, artifact-led, and runtime cases need different first checks. 4. Separate symptom triage from diagnosis — logs help you start, not finish. 5. Change one thing at a time — debugging is an experiment loop. 6. End with verification — every result should say how the cause was confirmed.

References

• Visual Studio Code: Debugging
• Playwright: Debugging Tests
• GitHub Docs: Enabling debug logging
• Git: git-bisect documentation
• Google Testing Blog: Flaky Tests at Google and How We Mitigate Them

Debugging Loop

Use this loop when the failure has moved beyond raw symptom collection and the next job is causal reasoning.

1. Define the failure

• expected vs actual
• trigger/input/state
• environment
• deterministic vs flaky
• known-good vs known-bad if available

2. Build the smallest reproducer

• one command, one test, one request, one UI flow, one fixture, or one commit range
• remove unrelated setup until the failure is cheap to rerun

3. Isolate the boundary

• code path
• data/fixture
• config/flag/env
• dependency/service
• timing/concurrency/order
• history/change range

4. Run a discriminating check

• inspect one suspect branch
• compare one good vs bad state
• rerun one focused test
• use git bisect when a reliable pass/fail signal exists
• add temporary instrumentation only at the narrowed boundary

5. Record keep/reject decisions

• hypothesis
• check performed
• result
• confidence

6. Verify the fix

• reproducer passes
• nearby edge cases still pass
• regression guard added

Practical rule

If you still cannot name the failing boundary, you are probably still in symptom triage and should sharpen the input first.

Handoff Boundaries for debugging

debugging owns

• Root-cause workflow after the symptom is clear enough to test
• Reproduction, minimization, isolation, hypothesis testing, and fix verification
• Regression isolation with recent-change comparison or git bisect
• Flaky-failure investigation when the immediate job is to stabilize and explain one failure

Route to log-analysis

Use log-analysis when the user mainly needs to know which lines matter or what the first actionable failure is.

Examples:

• pasted stack traces or CI logs with no narrowed suspect yet
• browser/network/server evidence that still needs initial correlation
• repeated retry storms where the first blocker is still unknown

Route to testing-strategies

Use testing-strategies when the main task becomes coverage design, test-layer planning, or broad flaky-test prevention policy rather than debugging one concrete failure.

Examples:

• redesigning the test pyramid
• deciding what belongs in unit vs integration vs E2E
• building org-wide flaky-test mitigation policy

Route to code-review

Use code-review when the user is primarily asking for preventive review of a change set, not active root-cause investigation.

Examples:

• review this PR for bugs/security/perf issues
• audit this diff for maintainability concerns
• check whether tests/docs are sufficient before merge

Route to performance-optimization

Use performance-optimization when the core job is measurement and optimization tradeoffs after the performance problem is already framed.

Examples:

• reduce p95 latency
• improve query plan or cache strategy
• tune CPU/memory hotspots with profiling data

Practical rule

• If the user mainly needs the important failing symptom, start with log-analysis.
• If the user mainly needs a reproduce → isolate → verify loop, use debugging.
• If the user mainly needs test-program architecture, use testing-strategies.
• If the user mainly needs preventive diff review, use code-review.
• If the user mainly needs optimization strategy, use performance-optimization.

Mode Selection and Fast Checks for debugging

Use this packet after the failure is concrete enough to test. The goal is to choose the cheapest discriminating check for the case type instead of defaulting to generic logging or broad patching.

1. Regression debugging

Choose this mode when the bug clearly used to work and you have a likely change window.

Fast checks:

• compare the suspect files or config range
• identify a last-known-good commit or release
• use git bisect if a reliable pass/fail check exists
• compare one good request/test/output against one bad one

Good prompts:

• "it started after the refactor"
• "this worked last week"
• "which commit introduced this"

Route out if:

• the task shifts into refactoring or PR-audit work → code-review / code-refactoring

2. Flaky-failure debugging

Choose this mode when the same code sometimes passes and sometimes fails.

Fast checks:

• measure the failure rate with repeated runs
• compare timing, shared state, retries, caching, clocks, random seeds, and order dependence
• decide whether the failure is product bug, test bug, or environment instability
• keep the rerun loop focused on one test, one scene, one worker, or one suspect boundary

Good prompts:

• "fails one out of eight runs"
• "passes locally, fails in CI"
• "non-deterministic"

Route out if:

• the job becomes suite-wide flake policy, quarantine design, or coverage planning → testing-strategies

3. Env / config mismatch debugging

Choose this mode when the bug only happens in CI, staging, prod, one device profile, or one runtime setup.

Fast checks:

• diff env vars, flags, dependency versions, secrets paths, locales, timezones, or container/runtime versions
• print or capture the exact config branch taken at runtime
• verify the same payload/input under both environments
• check file paths, permissions, seed data, and external-service assumptions

Good prompts:

• "only in staging"
• "works on my machine"
• "only in CI"
• "only on device X / browser Y"

Route out if:

• the task is really machine/setup reproducibility design → system-environment-setup

4. Artifact-led debugging

Choose this mode when you already have the first useful log, trace, screenshot, crash context, or failing request, but the cause is still unknown.

Fast checks:

• map the artifact to one suspect code path or state transition
• correlate the failing timestamp / request / span with the relevant module or config branch
• avoid broad log summaries once the meaningful clue is already known
• move from artifact → reproducible check as quickly as possible

Good prompts:

• "here's the first failing request payload"
• "the trace shows the crash in this span"
• "I know the failing step already"

Route out if:

• the task still mainly needs the first actionable failure identified → log-analysis

5. Runtime / browser / game-loop debugging

Choose this mode when live state, rendering, scene state, or user interaction matters as much as the raw code path.

Fast checks:

• reproduce the exact interaction path
• inspect runtime state, DOM/network events, scene state, or relevant engine/editor values
• reuse the same session when possible instead of recreating setup repeatedly
• separate logic bugs from frame-budget or perf-only complaints

Good prompts:

• "the button works in one browser but not another"
• "the scene breaks after this interaction"
• "the bug only appears while the game is running"

Route out if:

• the real task becomes profiling or bottleneck tradeoffs → performance-optimization / game-performance-profiler

Practical summary

• Known regression → compare recent change, maybe bisect
• Flaky → repeated-run evidence first
• Env-specific → diff facts before patching code
• Artifact clue already known → map artifact to one suspect boundary fast
• Runtime/UI/game interaction matters → reproduce the exact interaction path and inspect live state