---
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 BLoC / Cubit / Clean Architecture / Firebase / ios, android.
---

# Debug — TestApp

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

**Stack context:** **BLoC / Cubit** / **Clean Architecture** / **Firebase** / platforms: ios, android. Flavors: dev, prod. Codegen: freezed.

## 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: **dev, prod**. Confirm which flavor was active if the failure is env-specific.
5. **Platforms** — **ios, android**. Narrow reproduction to the platform that failed when relevant.
6. **Codegen** — tools: **freezed**. 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** — **unit_widget**; E2E tool: **patrol**. 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 **Clean Architecture**:
- presentation/ MUST NOT import from data/
- domain/ MUST NOT import from data/ or presentation/
- data/ CAN import from domain/ (implements interfaces)
- Use dependency injection to invert data → domain dependency
- Always consider: `.cursor/rules/flutter-core.mdc`, `.cursor/rules/security-standards.mdc`, `.cursor/rules/project-context.mdc`, and state-management rules for **BLoC / Cubit**.

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:** 1.0.5
