---
name: Debug issue
description: Triage failing tests, analyze, CI, or runtime errors with an evidence-first BugReport. Use /debug and paste logs; invokes systematic-debugging before fixes. Stack {{STATE_MANAGEMENT}} / {{ARCHITECTURE}} / {{BACKEND}} / {{PLATFORMS_LIST}}.
---

# Debug — {{PROJECT_NAME}}

Triage failures (tests, CI, runtime, or build) **without** jumping to fixes. Stay in hypothesis-and-evidence mode until root cause is stated.

**Stack context:** **{{STATE_MANAGEMENT}}** / **{{ARCHITECTURE}}** / **{{BACKEND}}** / platforms: {{PLATFORMS_LIST}}. Flavors: {{FLAVORS_LIST}}. Codegen: {{CODEGEN_LIST}}.

## Usage

```
/debug <what failed — paste error output, command, or symptom>
```

**Examples:**

- `/debug flutter test fails on auth_cubit_test — paste output`
- `/debug CI analyze step — paste log excerpt`
- `/debug app crashes on cold start after last change`

---

## Phase 0 — Normalize the report (BugReport)

Emit this skeleton **before** deep analysis. If the user already pasted logs, map them into the fields instead of re-asking.

| Field | Content |
|-------|---------|
| **Summary** | One line: what broke |
| **Expected** | What should happen |
| **Actual** | What happened (symptom + error text) |
| **Repro steps** | Numbered, minimal |
| **Scope / files touched** | Paths or PR slice |
| **Environment** | OS, Flutter/Dart version if known, device vs simulator, flavor |
| **Evidence** | Pasted command output, stack trace, or screenshot notes |

---

## Phase 1 — Evidence checklist (Flutter-aware)

Gather or request **concrete** evidence. Do not guess versions or config.

1. **`flutter doctor -v`** — paste output when environment is unknown or iOS/Android toolchain errors appear.
2. **Failing command** — full invocation + **verbatim** tail of output (e.g. `flutter test …`, `dart test …`, `flutter analyze`).
3. **`flutter analyze`** — if not already in the failure log, run or ask the user to run and paste.
4. **Flavors** — this project uses: **{{FLAVORS_LIST}}**. Confirm which flavor was active if the failure is env-specific.
5. **Platforms** — **{{PLATFORMS_LIST}}**. Narrow reproduction to the platform that failed when relevant.
6. **Codegen** — tools: **{{CODEGEN_LIST}}**. When this is not `none`, remind to run `dart run build_runner build --delete-conflicting-outputs` after generated files changed, and to align with `.cursor/hooks/` / `lefthook run pre-commit` when hooks are present.
7. **Testing depth** — **{{TESTING_DEPTH}}**; E2E tool: **{{E2E_TOOL}}**. Match the failure to the right layer (unit vs widget vs integration).

---

## Phase 2 — Root cause (no code yet)

> **Invoke skill: `superpowers:systematic-debugging`**

Produce **one paragraph**: hypothesis tied to **specific lines** in the pasted evidence. Mark confidence (high / medium / low). **No code changes** in this phase.

---

## Phase 3 — Fix (only after Phase 2)

> **Invoke skill: `superpowers:systematic-debugging`** again while iterating fixes.

When proposing changes:

- Respect architecture boundaries for **{{ARCHITECTURE}}**:
{{ARCH_IMPORT_RULES}}
- Always consider: `.cursor/rules/flutter-core.mdc`, `.cursor/rules/security-standards.mdc`, `.cursor/rules/project-context.mdc`, and state-management rules for **{{STATE_MANAGEMENT}}**.

After each fix attempt, re-run the **same** failing command and paste new output.

---

## ACTION REQUIRED

If evidence is missing, **stop** and print:

1. Exact commands to run (copy-paste ready).
2. What to paste back (full error blocks, not summaries).
3. If the user cannot run commands: state assumptions explicitly and set confidence to **low**.

**Template version:** {{TEMPLATE_VERSION}}