---
name: Explain code
description: Explain what code does without editing it. Use /explain with a path or symbol; covers {{STATE_MANAGEMENT}} state, {{BACKEND}} I/O, routing {{ROUTING}}, and failure modes. Ask when facts are not in the repo.
---

# Explain — {{PROJECT_NAME}}

Explain **what the code is doing** — **do not** change production code unless the user explicitly asks for a fix.

**Stack:** **{{STATE_MANAGEMENT}}** / **{{ARCHITECTURE}}** / **{{ROUTING}}** / **{{BACKEND}}** / platforms: {{PLATFORMS_LIST}}. Package: `{{PACKAGE_ID}}`.

## Usage

```
/explain <file path, widget name, class, or symbol>
```

**Examples:**

- `/explain lib/features/cart/cart_cubit.dart`
- `/explain how checkout routes after payment`
- `/explain CartPage build method`

---

## Output format (use these headings in order)

### Purpose

One short paragraph: why this code exists in the product context (**{{PROJECT_NAME}}** — {{DESCRIPTION}}).

### Public API

Surface area: public classes/methods, constructors, and what callers are expected to pass. Note codegen involvement when **{{CODEGEN_LIST}}** is not `none`.

### Call flow

Ordered steps from entry point (e.g. widget `build`, route handler, Bloc `on<Event>`, Riverpod `build`, GetX controller lifecycle) through collaborators. Tie navigation to **{{ROUTING}}** where relevant.

### State and side effects

How state is held and updated for **{{STATE_MANAGEMENT}}** ({{STATE_MGMT_RAW}}). Mention async work, listeners, and disposal. Reference **{{ARCH_IMPORT_RULES}}** if layering is unclear.

### I/O and backends

Network, local storage, or platform channels touching **{{BACKEND}}** (and **{{AUTH}}** where auth applies: {{AUTH_RAW}}). Do **not** invent API shapes not visible in the repo.

### Failure modes

What can go wrong: null paths, error states, race conditions, missing permissions on {{PLATFORMS_LIST}}, auth edge cases.

### Suggested tests

Ideas aligned with **{{TESTING_DEPTH}}** and **{{E2E_TOOL}}**; for **{{STATE_MANAGEMENT}}**, prefer patterns like:

```
{{TEST_PATTERN}}
```

### Unknowns — questions for you

If behavior depends on runtime config, native projects, remote API contracts, or secrets not in tree: **stop** and list **specific** questions. Do not fabricate facts.

---

## References

- **Project brief:** `project-brief.yaml` — feature modules: {{FEATURES_LIST}}; special features: {{SPECIAL_FEATURES}}.
- **Scale:** {{SCALE}}; i18n locales: {{LOCALES_LIST}} (when explaining localization).
- **Design:** {{DESIGN_SOURCE}}; Figma URL: {{FIGMA_URL}}.
- **API docs format:** {{API_DOCS_FORMAT}} (path: {{API_DOCS_PATH}}).
- **Related repos (if any):**

{{GIT_REFS_BLOCK}}

- **Local paths (if any):**

{{LOCAL_PATHS_BLOCK}}

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