v1.0.0 to v1.0.1

---

name: diagnose

license: MIT

description: Disciplined diagnosis and re-validation loop for hard bugs and performance regressions. Reproduce, minimise, hypothesise, instrument, fix, and regression-test. Use when the user says diagnose this / debug this, reports a bug, says something is broken/throwing/failing, or describes a performance regression. User-facing questions and findings must be in Portuguese (pt-BR). Part of the afonsoft/skills collection.

metadata:

visibility: public

author: afonsoft

url: https://github.com/afonsoft/skills

---

# Diagnose

A discipline for hard bugs and regressions. Skip phases only when explicitly justified. All questions and findings reported to the user must be in **Portuguese (pt-BR)**.

When exploring the codebase, use the project's domain glossary from `.claude/CONTEXT.md` to get a clear mental model of the relevant modules, and check `docs/architecture/` for decisions in the area you are touching.

**Re-validation loop**: after every hypothesis, fix, or change, re-run the reproduction and the regression checks before declaring the bug resolved.

## When to Use

- User asks or mentions this skill in English (e.g., "use /diagnose", "run diagnose").

- O usuário pede ou menciona esta skill em português (ex.: "use /diagnose", "execute diagnose").

## Phase 1 — Build a feedback loop

**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you do not have one, no amount of staring at code will save you.

Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**

### Ways to construct one — try them in roughly this order

1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.

2. **Curl / HTTP script** against a running dev server.

3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.

4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.

5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.

6. **Throwaway harness.** Spin up a minimised version of the problem in a new project, then debug that.

Ask the user in Portuguese when you need more data:

```text

Preciso de um exemplo minimo que reproduza o erro. Voce consegue me fornecer:

1. O comando ou acao que dispara o problema.

2. A saida ou mensagem de erro exata.

3. O ambiente (local, CI, staging, producao).

➡️ Se nao tiver, vou tentar construir um caso de reproducao sozinho.

```

## Phase 2 — Minimise the problem

**This is the skill.** If you cannot reproduce the bug in isolation, you cannot fix it. If you cannot minimise the problem, you cannot reproduce it. If you cannot reproduce it, you cannot fix it.

### Ways to minimise — try them in roughly this order

1. **Remove code** until the bug disappears. Add it back in small chunks to find the culprit.

2. **Remove data** until the bug disappears. Add it back in small chunks to find the culprit.

3. **Remove configuration** until the bug disappears. Add it back in small chunks to find the culprit.

4. **Remove dependencies** until the bug disappears. Add them back in small chunks to find the culprit.

5. **Remove environment** until the bug disappears. Add it back in small chunks to find the culprit.

## Phase 3 — Hypothesise

**This is the skill.** If you cannot explain the bug, you cannot fix it.

### Ways to hypothesise — try them in roughly this order

1. **Check the obvious.** Is the bug in the code you are looking at? Is it in the code you are calling? Is it in the code calling you?

2. **Check the documentation.** Is the bug in the docs you are looking at? Is it in the docs you are calling?

3. **Check the logs.** Are the logs telling the truth? Are they masking the real error?

4. **Check the tests.** Is the bug in the tests you are running? Are they covering the real path?

5. **Check the codebase.** Are there other call sites with the same pattern?

Report the hypothesis to the user in Portuguese:

```text

Hipotese atual: [DESCRICAO_DA_HIPOTESE].

Vou validar com [ACAO_EXPERIMENTAL]. Se confirmar, o proximo passo e [PROXIMO_PASSO].

Concorda ou quer que eu teste outra hipotese primeiro?

```

## Phase 4 — Instrument

**This is the skill.** If you cannot see the bug, you cannot fix it.

### Ways to instrument — try them in roughly this order

1. **Add logs** around the suspect seam.

2. **Add metrics** to measure the suspect behaviour.

3. **Add traces** to follow the request path.

4. **Add assertions** to fail fast on invariants.

5. **Add tests** that reproduce the bug before the fix.

## Phase 5 — Fix

Do the smallest, safest change that removes the root cause. Avoid band-aids. If the fix touches many files, present the plan to the user in Portuguese before editing.

```text

Raiz do problema: [RAIZ].

Correcao proposta: [DESCRICAO_DA_CORRECAO].

Arquivos afetados: [LISTA].

Posso aplicar a correcao e depois rodar os testes?

```

## Phase 6 — Regression-test and re-validate

**This is the skill.** If you cannot verify the fix, you cannot call it done.

### Required checks

1. **Reproduction fails before the fix, passes after.**

2. **Add a regression test** for the fixed bug.

3. **Run the affected test layer** (unit, integration, E2E).

4. **Run a lightweight regression** on neighbouring flows.

5. **Remove or revert instrumentation** that is no longer needed.

Report the result in Portuguese:

```text

Correcao aplicada em [ARQUIVOS].

- Teste de reproducao: [PASS/FAIL]

- Testes de regressao: [PASS/FAIL]

- Testes afetados: [PASS/FAIL]

O bug esta resolvido. Quer que eu abra uma Issue para documentar a causa raiz com /create-issues?

```

## Agent Self-Debug / Introspection (use when the failure is the agent itself)

If the bug is not in the codebase but in the agent session — repeated tool-call failures, loops, context drift, or mismatch between expected and actual filesystem state — apply the agent-introspection loop.

### Phase A — Failure Capture

Before trying to recover, record:

- error type, message, and stack trace when available

- last meaningful tool call sequence

- what the agent was trying to do

- current context pressure: repeated prompts, oversized pasted logs, duplicated plans, or runaway notes

- current environment assumptions: cwd, branch, relevant service state, expected files

```markdown

## Failure Capture

- Session / task:

- Goal in progress:

- Error:

- Last successful step:

- Last failed tool / command:

- Repeated pattern seen:

- Environment assumptions to verify:

```

### Phase B — Root-Cause Diagnosis

Match the failure to a known pattern:

| Pattern | Likely Cause | Check |

| --- | --- | --- |

| Maximum tool calls / repeated same command | loop or no-exit observer path | inspect the last N tool calls for repetition |

| Context overflow / degraded reasoning | unbounded notes, repeated plans, oversized logs | inspect recent context for duplication and low-signal bulk |

| `ECONNREFUSED` / timeout | service unavailable or wrong port | verify service health, URL, and port assumptions |

| `429` / quota exhaustion | retry storm or missing backoff | count repeated calls and inspect retry spacing |

| file missing after write / stale diff | race, wrong cwd, or branch drift | re-check path, cwd, git status, and actual file existence |

| tests still failing after “fix” | wrong hypothesis | isolate the exact failing test and re-derive the bug |

Diagnosis questions:

- is this a logic failure, state failure, environment failure, or policy failure?

- did the agent lose the real objective and start optimizing the wrong subtask?

- is the failure deterministic or transient?

- what is the smallest reversible action that would validate the diagnosis?

### Phase C — Contained Recovery

Prefer these interventions in order:

1. Restate the real objective in one sentence.

2. Verify the world state instead of trusting memory.

3. Shrink the failing scope.

4. Run one discriminating check.

5. Only then retry.

Bad pattern: retrying the same action three times with slightly different wording.

Good pattern: capture failure → classify the pattern → run one direct check → change the plan only if the check supports it.

### Phase D — Self-Debug Report

End with:

```markdown

## Agent Self-Debug Report

- Session / task:

- Failure:

- Root cause:

- Recovery action:

- Result: success | partial | blocked

- Token / time burn risk:

- Follow-up needed:

- Preventive change to encode later:

```

## Silent-Failure Hunt

When the code "works" but misbehaves quietly, hunt for silent failures before declaring the bug resolved.

### Hunt Targets

1. **Empty Catch Blocks** — `catch {}`, ignored exceptions, errors converted to `null` / empty arrays with no context.

2. **Inadequate Logging** — logs without enough context, wrong severity, log-and-forget handling.

3. **Dangerous Fallbacks** — default values that hide real failure, `.catch(() => [])`, graceful-looking paths that make downstream bugs harder to diagnose.

4. **Error Propagation Issues** — lost stack traces, generic rethrows, missing async handling.

5. **Missing Error Handling** — no timeout or error handling around network/file/db paths, no rollback around transactional work.

### Output Format

For each finding:

- location

- severity

- issue

- impact

- fix recommendation

## Re-Validation Loop

Diagnosis is iterative. After every change, re-run the reproduction. If the bug moves or changes, go back to Phase 3. Do not declare the bug fixed until the reproduction passes and the regression suite is green.

## Common Mistakes

| Mistake | Fix |

| --- | --- |

| Fixing without a reproduction first | Build a reproduction before changing code. |

| Skipping minimisation | Minimise first, or you fix symptoms, not the cause. |

| Removing instrumentation too early | Keep it until the fix is verified. |

| Not adding a regression test | Every fixed bug deserves a test. |

| Declaring done without re-validation | Re-run the reproduction and the suite. |

## References

- `qa-analyst` — for test planning and bug reporting

- `grill-me-with-spec` — for producing specs when the bug reveals missing requirements

- `improve-codebase-architecture` — when the diagnosis reveals structural seams that need deepening

- `agent-introspection-debugging` — when the failure is the agent session itself (loops, context drift, repeated tool calls)

- `silent-failure-hunter` — when the code works but misbehaves quietly