Guardian — AGENTS.md

This file makes Guardian's production-debugging method available to any AI coding agent that reads AGENTS.md (Codex CLI, Cursor, GitHub Copilot, Windsurf, Amp, Devin, Aider, Zed, Jules, VS Code, JetBrains Junie, and others). It is the flat-file adapter of the Guardian skill. The full per-domain knowledge lives in the references/ directory next to this file — read the relevant reference on demand as directed below.

If you are running in a tool that supports the open agent skills spec (Claude Code, Claude.ai, Codex skills), prefer installing the SKILL.md skill folder instead — it adds automatic triggering and on-demand loading. See INSTALL.md.

When to apply this

Apply Guardian's method whenever the user is dealing with a production issue: an outage, a crash, an error, a failing service, a slow endpoint, a memory leak, a crashing pod, a confusing dashboard — or whenever they paste a stack trace, logs, a Sentry issue, or output from Datadog, Kubernetes, an APM, or any observability tool. Also when they just say "my app is down," "why is this 500-ing," "this is slow in prod," or "what does this log mean."

Core principle: evidence before hypothesis

Do not guess a cause and then look for evidence to confirm it — that wastes hours. Instead: gather the signal → reconstruct the timeline → localize the failure to a layer → form a hypothesis only once evidence points somewhere → verify it against the evidence → propose a fix plus the exact way to confirm it. If evidence is insufficient, say so and name precisely what additional signal would unblock the analysis. Never fill a gap with a confident guess.

The method

1. Intake. Classify the signal in front of you and open the matching reference (table below).
2. Reconstruct the timeline. Order events; find the earliest anomaly, not the loudest error — the loud symptom (a 500 storm, an OOM) is usually downstream. Anchor to any deploy/config change whose timing lines up.
3. Localize. A request flows client → edge/LB → app code → data layer → external deps, with runtime/host underneath. Find which layer owns the failure before reasoning about why. A failure with no app log is a strong signal the problem is upstream of the app.
4. Correlate (if multiple signals). When you have more than one signal, pivot between them on shared keys (time window, trace_id, release, host) to converge on one cause. Read references/cross-signal-correlation.md. A hypothesis confirmed by several independent signals is strong; from one signal it's a guess.
5. Root cause + fix. State the cause separately from the symptom. Give an immediate mitigation, the real fix, and the exact signal that verifies it's resolved.

Dispatch table — read the matching reference

These references are plain Markdown — open the one that matches and follow it. This mimics, by hand, the on-demand loading that the native skill does automatically.

Output

Match the response to the size of the problem.

Short mode (unambiguous cause, small fix — a typo, a wrong variable, a clear chained exception):

**The real problem:** [the cause, not the symptom — one sentence]
**Fix:** [the concrete change]
**Verify:** [the signal that confirms it]

Full mode (cause not obvious, multiple layers, real outage, timeline matters):

## What's happening   [symptom, 1-2 sentences]
## Timeline           [ordered events, earliest anomaly → loud symptom]
## Root cause         [cause, separated from symptom, with supporting evidence]
## Fix
**Now:** [immediate mitigation]   **Real fix:** [root-cause resolution]   **Verify:** [signal that confirms]
## If I'm wrong       [next most likely cause and what evidence would point there]

Even in short mode, name the cause, not the loud symptom. The brevity is in the formatting, not the rigor. When evidence genuinely isn't enough, the honest "here's what I can rule out, here's what I'd need to go further" beats a confident wrong answer.