---
description: Systematic regression-tracing skill from symptom and error evidence to root cause, fix, and prevention.
name: diagnose
---

<!-- Auto-generated from @maestria/core. Do not edit directly.
     Edit the canonical file at packages/core/agent-directives/ instead. -->

You trace bugs systematically.

## Human-Facing Output

- **!!! Human-facing output.** Apply the canonical human-facing output contract to authored responses, reports, comments/docstrings, commit messages, PR titles/bodies/descriptions, and documentation. Never emit Unicode U+2014 EM DASH. Preserve code syntax, literals, quoted source, and user-provided text.

## Investigation Strategy

Start from the observed failure and choose the next check that distinguishes plausible causes. The sections below are investigation aids, not a mandatory itinerary. Stop investigating when the cause and affected contract are supported by evidence; continue through any authorized repair and verification.

## Step 1: Error -> Source Location

Translate error message into actual source code:

- Find corresponding source file (not dist/minified)
- Identify exact line and function
- Search for unique strings if stack trace is minified

## Step 1.5: Check Environment (Autonomously)

Rule out environmental causes by gathering data directly when symptoms suggest configuration or runtime differences:

- Check relevant dependency manifests and lockfiles for recent changes using the project's diff/version-control tools
- Check `.env.example` vs `.env` for missing vars
- Check relevant runtime and package-manager versions for known incompatibilities
- Check working directory assumptions against actual project structure

Document relevant checks, ruled-out causes, and material assumptions without exposing secret values.

## Step 2: Source -> Git History

Inspect history when it helps locate a regression or explain surprising behavior:

- `git blame` on the problematic line
- Read the commit message and diff
- Consider source, caller, dependency, configuration, and environment changes. An old line alone does not establish when the failure began; report uncertainty when history cannot establish the trigger.

## Step 3: Git History -> Blast Radius

Expand to similar sites when the cause indicates a shared defect or the requested scope includes an audit:

- Search for the same unsafe pattern
- Report affected sites and evidence; use a table when comparison helps
- Document which are safe vs unsafe

## Step 4: Blast Radius -> Minimal Fix

If the assignment and host permit repair, fix the root cause with minimal changes; otherwise hand the supported diagnosis to the implementation owner:

- Fix root cause, not symptom
- Prefer existing dependencies; assess any necessary addition against scope, maintenance, and authorization constraints
- Choose the smallest correct repair, not the fewest lines
- Add validation or error handling only where it addresses the demonstrated cause
- Check the consequence of a system change and obtain any missing authorization

## Step 5: Fix -> Prevention

Prevent similar bugs:

- Consider regression tests where a durable contract or plausible recurrence justifies them (per Global Rules testing judgment)
- Consider linting rules to catch the pattern
- **!!! Preserve durable diagnostic lessons** - update an existing knowledge artifact when one fits; create one only when the findings have durable future value or the user/project requires a record.

## Step 6: Verify Fix

Confirm it works:

- Run existing tests
- Reproduce original error (should be fixed)
- Check for unintended side effects
- Prepare rollback plan **!!! Always verify before handoff** - Never present broken code.

## Rules

- **!!! Edit and system-change permissions follow the host policy** - explain the rationale before any change and use the platform's approval controls.
- **!!! Use relevant available evidence before asking**; document material assumptions with supporting evidence and proceed on ordinary ambiguity.
- **Parallelization:** different bugs in parallel; same bug = consolidate.

## Output Format & Handoff

Document: what was investigated, ruled out, root cause, fix, prevention, and tagged assumptions (`[verified]`/`[inferred]`).

## Skills

Load on trigger: `agent-browser`, `webapp-testing`, `logging-best-practices`, `dependency-updater`. Skip when no skill matches the bug category.