Use this file to create an agent skill/command to hunt logs

hunt-crash-log

---
name: hunt-crash-log
description: >
  Use this skill when the user pastes a Firebase Crashlytics crash log,
  raw exception/stack-trace text, or a screenshot of breadcrumbs.
  Also triggers on phrases like "hunt this crash", "debug this crash",
  "crashlytics log", "breadcrumbs", "investigate this crash", "crash report".
---

# Hunt Crash Log

You are diagnosing a bug from a Firebase Crashlytics crash log for a Flutter app.
Follow the workflow below every time.

---

## Step 0 — Discover the project (run once per session)

Before diagnosing anything, build a mental map of the codebase. Find and
memorize the following. Use your own judgment on how best to locate each one.

1. **Exception hierarchy** — Find the base app exception class, its subtypes
   (mapped to HTTP status codes like 400, 401, 403, 404, 422, 429, etc.),
   and the factory method that converts raw errors into domain exceptions.

2. **HTTP client** — Find where HTTP calls are made and how failures are thrown
   (e.g. a `throwOnFailure` helper, a Dio interceptor, etc.).

3. **Error response parser** — Find the utility that extracts structured error
   info (like an error key or user-facing message) from API response bodies.

4. **Logger** — Find the app's logger singleton, its call signatures for
   error/debug logging, and any Crashlytics breadcrumb formatter.

5. **Global error handler** — Find the top-level handler
   (e.g. `runZonedGuarded`, `FlutterError.onError`). Note which exception
   types it skips — those won't appear in Crashlytics directly.

6. **Routes** — Find the route definitions so you can map a breadcrumb route
   string back to a page and its viewmodel/bloc/controller.

7. **Architecture layout** — Understand the folder structure and layer
   conventions (Clean Architecture, feature-first, MVC, etc.) so you know
   where presentation, domain, and data code lives.

8. **Localization** — Locate the localization files (ARB, JSON, etc.) for
   checking known error message keys.

> **Keep all discovered paths, class names, and patterns in working memory.**
> Reference them in every subsequent step.

---

## Step 1 — Parse the input

- **Raw text**: extract exception type, message, and every stack frame.
- **Screenshot**: read breadcrumbs top-to-bottom; note all `[error]` lines and
  the most recent `Route:` line.
- Record: exception type · message · screen/route · key stack frames.

## Step 2 — Locate the source

1. Find the exact logger call that produced the error message → identifies the
   ViewModel/Bloc/Controller method.
2. Find the repository method visible in the stack trace.
3. Map the route from breadcrumbs → route definitions → page + viewmodel.

## Step 3 — Trace the architecture

Walk backwards through the project's layers:

- **Presentation** — The component that caught and logged the error.
- **Domain** — The use case being orchestrated.
- **Data** — The repository + API endpoint that made the call.

## Step 4 — Identify root cause

Use the exception hierarchy discovered in Step 0 to classify:

| Exception pattern | Likely cause | Key detail to extract |
|---|---|---|
| Bad request (400) | Missing field / malformed body / business rule | Response body error key |
| Unauthorized (401) | Expired or missing auth token | Token refresh flow |
| Forbidden (403) | Permission / ownership issue | User role or resource ownership |
| Not found (404) | Wrong endpoint or resource missing | Endpoint URL in breadcrumb |
| Unprocessable (422) | Validation failure | Response body error key |
| Network error | Connectivity / timeout | Network conditions |
| Unknown / unmapped | Unexpected; read original exception | Raw exception type |
| Not a domain exception | Unhandled; caught by global handler | Raw type + stack trace |

For HTTP errors, extract the response body from the raw HTTP exception class
and parse it using the error response parser — both found in Step 0.

## Step 5 — Suggest a fix

Always follow **the project's own conventions** as discovered in Step 0:

- Repositories must wrap catches with the project's exception factory.
- ViewModels/Blocs must log with the project's logger, then set error state.
- No `print()` — use the project's logger.
- Use package imports only (no relative imports).
- If the project uses code generation (Freezed, json_serializable, etc.),
  remind to run `dart run build_runner build` for new fields.
- For known error keys, check localization files or add a guard/recovery.

## Step 6 — Verify the fix

Suggest a unit test when possible. If the crash is caused by external factors
(OS, network, device-specific quirk), state that it's not directly actionable
and recommend defensive handling or monitoring.

---

## Output Format

Structure every response as (keep it copy-paste-friendly):

```
**Crash Summary**
- Exception type: …
- Screen / Route: …
- Last user action (from breadcrumbs): …

**Root Cause**
[Technical explanation with file + line references]

**Relevant Code**
[Snippet from the identified file with file_path:line_number]

**Suggested Fix**
[Concrete, minimal code change following project patterns]
```