feat(flutter-cursor-templates): add /debug, /verify, /explain skills and goldens.
Wire debug-issue, verify-change, and explain-code into the universal resolver with reasons, extend AGENTS.md slash list, cross-link build Phase 3 and Phase 6, refresh generator goldens for three stacks, and note cross-skill links in the build skill design spec. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -346,6 +346,7 @@ Follow Red → Green → Refactor strictly. Show actual terminal output at each
|
||||
flutter test test/features/[feature]/ --no-pub
|
||||
```
|
||||
**Paste the actual output here before proceeding.**
|
||||
If failures are unclear or non-deterministic after one iteration, use **`/debug`** with full pasted output before guessing fixes.
|
||||
|
||||
### Step 3b — Green: Implement
|
||||
|
||||
@@ -371,6 +372,8 @@ Follow Red → Green → Refactor strictly. Show actual terminal output at each
|
||||
**Paste the actual output here before proceeding.**
|
||||
3. Run tests once more to confirm still green.
|
||||
|
||||
If output stays red or errors are ambiguous after two focused attempts, stop and use **`/debug`** with the full failing command and log before changing more code.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Integration Test Generation
|
||||
@@ -503,6 +506,8 @@ VERIFICATION REQUIRED — paste real output for each:
|
||||
```
|
||||
|
||||
If any check fails: invoke `superpowers:systematic-debugging` to diagnose before retrying.
|
||||
For noisy errors or weak reproduction, run **`/debug`** and fill the BugReport skeleton with logs before retrying.
|
||||
For small, isolated changes, **`/verify`** is enough to re-check tests and analyze without re-reading this whole skill.
|
||||
Do not proceed to Phase 7 until all four checks are green.
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
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}}
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
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}}
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
name: Verify change
|
||||
description: Post-change or pre-PR verification without the full /build lifecycle. Use /verify with optional scope; respects testing depth {{TESTING_DEPTH}} and E2E {{E2E_TOOL}}; no success claims without pasted outputs.
|
||||
---
|
||||
|
||||
# Verify — {{PROJECT_NAME}}
|
||||
|
||||
Run a **focused** verification gate after a change or before a small PR — without replaying the entire `/build` document.
|
||||
|
||||
**Stack:** **{{STATE_MANAGEMENT}}** / **{{ARCHITECTURE}}** / **{{BACKEND}}** / {{PLATFORMS_LIST}}. **Testing depth:** {{TESTING_DEPTH}}. **E2E tool:** {{E2E_TOOL}}. **Codegen:** {{CODEGEN_LIST}}.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/verify [optional scope: paths, “small PR”, or feature name]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
- `/verify lib/features/auth/`
|
||||
- `/verify small PR before push`
|
||||
- `/verify after dependency bump`
|
||||
|
||||
---
|
||||
|
||||
## Checklist (adapt to testing depth)
|
||||
|
||||
> **Invoke skill: `superpowers:verification-before-completion`**
|
||||
|
||||
**Do not claim success** until the user (or you, in a trusted environment) has pasted **real** output for each applicable item below.
|
||||
|
||||
### Always (typical Flutter repo)
|
||||
|
||||
- [ ] **Unit / widget tests** for touched code — e.g. `flutter test <path> --no-pub` or full suite as appropriate.
|
||||
**Required in paste:** a line showing tests passed (or the exact failure to fix).
|
||||
- [ ] **`flutter analyze`**
|
||||
**Required in paste:** `No issues found!` or the analyzer errors to address.
|
||||
|
||||
### When `testing.depth` is `full` or `e2e` (this brief: **{{TESTING_DEPTH}}**)
|
||||
|
||||
- [ ] **Integration / E2E** — use **{{E2E_TOOL}}** patterns from `.cursor/rules/` (e.g. Patrol). Run on a device or emulator when scenarios require it; paste run output.
|
||||
|
||||
### When `testing.depth` is `unit_widget` only
|
||||
|
||||
- [ ] **Integration / device E2E** — *not* mandatory unless the change touches integration-only surfaces; if skipped, say so explicitly in the paste.
|
||||
|
||||
### Hooks and codegen
|
||||
|
||||
- [ ] **`lefthook run pre-commit`** — run when the repo has Lefthook configured (especially when **{{CODEGEN_LIST}}** is not `none`). Paste hook summary.
|
||||
If hooks are not set up for this workspace, write *“skipped — hooks not configured”* instead of failing silently.
|
||||
|
||||
### CI alignment
|
||||
|
||||
- [ ] For **{{CICD_TOOL}}** ({{CICD_RAW}}): confirm the same commands the pipeline runs (analyze + tests) are green locally. Note flavor-scoped secrets for **{{FLAVORS_LIST}}**.
|
||||
|
||||
---
|
||||
|
||||
## ACTION REQUIRED — paste block
|
||||
|
||||
Print this table and wait for pasted output before declaring done:
|
||||
|
||||
```
|
||||
VERIFICATION — paste real output for each line you executed:
|
||||
|
||||
[ ] flutter test … → (paste: pass count or failures)
|
||||
[ ] flutter analyze → (paste: no issues or errors)
|
||||
[ ] integration / e2e (if depth is full/e2e or change requires it) →
|
||||
[ ] lefthook run pre-commit → (paste or "skipped — not configured")
|
||||
```
|
||||
|
||||
If anything fails: switch to **`/debug`** with the failing log before guessing.
|
||||
|
||||
**Template version:** {{TEMPLATE_VERSION}}
|
||||
Reference in New Issue
Block a user