---
name: diagnose
description: 'Investigate and fix open issues in the .copilot/issues/ folder using test-first debugging. Use when asked to diagnose, triage, or work through unresolved bug reports, or when the user mentions open issues that need fixing.'
context: fork
---

# Diagnose Issues

## When to Create Issue Docs

Create a `.copilot/issues/YYYY-MM-DD-<slug>/` folder with `report.md` and `summary.md` when ANY of the following are true:

- A bug is reported and fixed (by user, by tests, or discovered during review)
- A production incident is investigated (even if the root cause is external)
- A deploy fails and requires investigation beyond a simple retry
- A smoke test fails and the fix is non-obvious
- A review cycle finds critical issues that require code changes

Do NOT create issue docs for:
- Typos, formatting fixes, or trivial one-line changes
- Review suggestions that are improvements, not bugs
- Planned refactors that aren't fixing a broken behavior

## Diagnose Flow

For each unresolved issue (folders in `.copilot/issues/` without a `summary.md`):

1. **Log the issue** — create `.copilot/issues/YYYY-MM-DD-<slug>/report.md` BEFORE starting the investigation. Include: one-line summary, impact (who/what is affected and severity), reproduction steps or error logs, and investigation notes as you work.

2. **Investigate** — read `report.md`, reproduce the problem, identify the root cause. Rule out false leads and record what was checked.

3. **Write a failing test** — create a test that captures the observed broken behavior. Run it to confirm it fails for the right reason. Do not skip this step — a fix without a regression test is incomplete.

4. **Fix the code** — make the minimal change to pass the test. Run the full test suite to confirm no regressions.

   **This step is the best `/goal` candidate in the whole workflow.** The failing test from step 3 was
   written *before* the fix and by a different step than the one being verified, so it does not inherit
   the implementation's assumptions the way a self-authored test suite does. That makes it a sound stop
   condition for a self-checking loop, where most criteria are not. Invoke it yourself — `/goal` is
   user-typed, not something this skill can start:

   ```
   /goal --max 3 make `pytest tests/test_<module>.py::<test_name>` pass without breaking the rest of the suite
   ```

   Phrase the goal as the command, not the outcome. "Make the test pass" is verifiable; "fix the bug" is
   not. Do NOT extend the goal through steps 5-6 — the gates are judgments and must not be wrapped
   (see `delivery-workflow.md` → *Goal-loop tasks*).

5. **Review gate** — after the fix is applied and tests pass, delegate to `reviewer`. Wait for a PASS verdict before proceeding. This gate is **sequential** — do not launch review and security review at the same time.

6. **Security review gate** — after the review gate returns PASS, delegate to `security-reviewer`. Wait for a PASS verdict before proceeding. This gate is **sequential** — it runs only after the review gate completes.

7. **Document** — write `.copilot/issues/<slug>/summary.md` with root cause, fix applied (with file paths), prevention measures, and status.

> ⚠️ **ANTI-PATTERN — DO NOT PARALLELIZE GATES**
>
> The review gate (step 5) and security review gate (step 6) are **sequential** and must not be
> launched in parallel. The correct order is: review → wait for PASS → security review → wait for
> PASS → document. Speed does not justify skipping gates.

## File Templates

### `report.md` — Written BEFORE or DURING investigation

```markdown
# Issue: <Title>

## Summary
One-line description of the problem.

## Impact
Who/what is affected and severity.

## Reproduction
Steps to reproduce, environment details, relevant logs.

## Investigation
What was checked, what was ruled out, root cause analysis.
```

### `summary.md` — Written AFTER the fix is verified and both gates pass

```markdown
# Resolution: <Title>

## Root Cause
What caused the issue (the actual reason, not the symptom).

## Fix Applied
What changed and where — file paths, not just descriptions.

## Prevention
Tests added, monitoring, guardrails — what stops this from happening again.
"Added a test" is the minimum. "Nothing" is not acceptable for non-trivial issues.

## Status
RESOLVED | MITIGATED | WONT_FIX
```

## Rules

1. **No silent fixes** — if you change code to fix a bug, document why. A fix without a `summary.md` is incomplete work.
2. **Link issues to plans** — if the issue was found during a plan's review cycle, reference the plan slug in `report.md`.
3. **Prevention is mandatory** — every `summary.md` must have a Prevention section. "Nothing" is not acceptable for non-trivial issues.
4. **Keep it concise** — issue docs are reference material, not narratives. Bullet points over paragraphs.
5. **Failing test before fix** — always write the failing test first (step 3), then fix the code (step 4). This order is the point of the skill.

## Workflow Integration

### During plan work (Phase 3: Fix)
When a review cycle finds critical or warning issues that require fixes:
1. Create `.copilot/issues/YYYY-MM-DD-<slug>/report.md` describing the problem found
2. Write a failing test that captures the broken behavior
3. Apply the fix (via fix tasks in `tasks.md`)
4. Run the review gate → wait for PASS
5. Run the security review gate → wait for PASS
6. Write `.copilot/issues/YYYY-MM-DD-<slug>/summary.md` with root cause, fix applied, and prevention

### Outside plan work (ad-hoc bug fixes)
When fixing a bug that doesn't warrant a full plan:
1. Create `.copilot/issues/YYYY-MM-DD-<slug>/report.md` BEFORE starting the fix
2. Write a failing test
3. Investigate and fix the issue
4. Run the review gate → wait for PASS (sequential)
5. Run the security review gate → wait for PASS (sequential)
6. Write `summary.md` after both gates pass

### Post-deploy failures
When a deploy or smoke test fails:
1. Create `.copilot/issues/YYYY-MM-DD-<slug>/report.md` with reproduction steps and logs
2. Write a failing test capturing the failure
3. Investigate and fix
4. Run the review gate, then the security review gate (sequential, never parallel)
5. Write `summary.md` with root cause and what prevents recurrence