---
name: zen-diagnose
description: Reproduce an observable defect, isolate its cause in the actual implementation and verify a targeted correction. Use for bugs, broken integration or behavior that differs from evidence.
---
# Zen diagnose

Build a reliable feedback loop before prescribing a fix.

1. Capture expected versus observed behavior, trigger, environment/version, frequency and affected scope. Read exact error/output without exposing credentials. Ask only for missing reproduction information you cannot discover locally.
2. Establish a baseline. Reproduce at the highest practical observable boundary: browser action, API response, command, native process or provider tool use. An HTTP 200 or success toast may precede the failure; inspect the resulting files/state. Label fixture-only reproductions.
3. Trace the real request/event path and inspect relevant code, types, configuration, tests and recent changes. Separate plausible hypotheses; identify the observation that would distinguish them. Do not rewrite architecture before isolating the symptom.
4. Run one bounded experiment at a time, preserving user data, dirty work and credentials. Use isolated copies when a crash/retry/destructive case matters. Do not repeat the same failed approach unchanged; inspect the new evidence and change the hypothesis.
5. If correction is authorized in the current assignment, make the smallest complete fix. Otherwise create a runnable bug TSK with reproduction and scope. Select a real model only through the owner's configured choice; diagnosis itself does not grant a new provider run.
6. Rerun the original reproduction, then relevant regression/project checks. Verify native/provider-facing behavior at its real boundary when authorized; a mocked adapter is limited evidence. Confirm no unrelated state/credentials changed.
7. Record cause, evidence, correction and limitations in a LOG/DOC or bug task, linking research/session/artifact as relevant. Use [the diagnosis worksheet](references/output.md) and [record operations](../zen/references/tools.md), or standalone capture. Preserve exact failed evidence rather than rewriting the log to show only success.

## Completion

Report reproduced/fixed/verified separately. If you cannot reproduce, supply the environment, hypotheses eliminated, what remains unknown and the exact next experiment. Do not declare a fix from code inspection alone. Pass implementation through Review, keep unresolved checks explicit and propose a targeted learning only when evidence supports it.

Example: a local check passes while the installed CLI receives no tool call. Verify workspace inspection/file changes from the actual provider; changing a health endpoint does not resolve that symptom.