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:
@@ -3,3 +3,4 @@
|
||||
Repo-level notes for AI assistants. Authoritative stack and conventions are in `project-brief.yaml` and `.cursor/` (regenerate with `cursor_gen` from the project root).
|
||||
|
||||
- **Package:** `com.test.taskflow`
|
||||
- **Slash skills** (see `.cursor/skills/`): `/build`, `/debug`, `/verify`, `/explain`
|
||||
|
||||
+5
@@ -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
|
||||
|
||||
@@ -373,6 +374,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
|
||||
@@ -505,6 +508,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.
|
||||
|
||||
---
|
||||
|
||||
+88
@@ -0,0 +1,88 @@
|
||||
---
|
||||
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 Riverpod / Feature-First / Supabase / ios, android, web.
|
||||
---
|
||||
|
||||
# Debug — TaskFlow
|
||||
|
||||
Triage failures (tests, CI, runtime, or build) **without** jumping to fixes. Stay in hypothesis-and-evidence mode until root cause is stated.
|
||||
|
||||
**Stack context:** **Riverpod** / **Feature-First** / **Supabase** / platforms: ios, android, web. Flavors: dev, prod. Codegen: freezed, json_serializable.
|
||||
|
||||
## 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, web**. Narrow reproduction to the platform that failed when relevant.
|
||||
6. **Codegen** — tools: **freezed, json_serializable**. 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 **Feature-First**:
|
||||
- features/auth/ MUST NOT import from features/home/ etc.
|
||||
- Shared code lives in core/ or shared/ only
|
||||
- Each feature is self-contained: screen + provider + model + repo
|
||||
- Always consider: `.cursor/rules/flutter-core.mdc`, `.cursor/rules/security-standards.mdc`, `.cursor/rules/project-context.mdc`, and state-management rules for **Riverpod**.
|
||||
|
||||
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.4
|
||||
+82
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: Explain code
|
||||
description: Explain what code does without editing it. Use /explain with a path or symbol; covers Riverpod state, Supabase I/O, routing GoRouter, and failure modes. Ask when facts are not in the repo.
|
||||
---
|
||||
|
||||
# Explain — TaskFlow
|
||||
|
||||
Explain **what the code is doing** — **do not** change production code unless the user explicitly asks for a fix.
|
||||
|
||||
**Stack:** **Riverpod** / **Feature-First** / **GoRouter** / **Supabase** / platforms: ios, android, web. Package: `com.test.taskflow`.
|
||||
|
||||
## 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 (**TaskFlow** — Task management app).
|
||||
|
||||
### Public API
|
||||
|
||||
Surface area: public classes/methods, constructors, and what callers are expected to pass. Note codegen involvement when **freezed, json_serializable** 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 **GoRouter** where relevant.
|
||||
|
||||
### State and side effects
|
||||
|
||||
How state is held and updated for **Riverpod** (riverpod). Mention async work, listeners, and disposal. Reference **- features/auth/ MUST NOT import from features/home/ etc.
|
||||
- Shared code lives in core/ or shared/ only
|
||||
- Each feature is self-contained: screen + provider + model + repo** if layering is unclear.
|
||||
|
||||
### I/O and backends
|
||||
|
||||
Network, local storage, or platform channels touching **Supabase** (and **Supabase Auth** where auth applies: supabase_auth). 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 ios, android, web, auth edge cases.
|
||||
|
||||
### Suggested tests
|
||||
|
||||
Ideas aligned with **unit_widget** and **patrol**; for **Riverpod**, prefer patterns like:
|
||||
|
||||
```
|
||||
final container = ProviderContainer(overrides: [myProvider.overrideWithValue(mockValue)]); addTearDown(container.dispose);
|
||||
```
|
||||
|
||||
### 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: auth, tasks, profile; special features: .
|
||||
- **Scale:** small; i18n locales: en, fr (when explaining localization).
|
||||
- **Design:** none; Figma URL: .
|
||||
- **API docs format:** none (path: ).
|
||||
- **Related repos (if any):**
|
||||
|
||||
_No Git repository URLs listed._ Add entries under `references.repos` in project-brief.yaml when other repos are part of the product context.
|
||||
|
||||
- **Local paths (if any):**
|
||||
|
||||
_No local paths listed._ Add monorepo packages or sibling folders under `references.local_paths` in project-brief.yaml when relevant.
|
||||
|
||||
**Template version:** 1.0.4
|
||||
+73
@@ -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 unit_widget and E2E patrol; no success claims without pasted outputs.
|
||||
---
|
||||
|
||||
# Verify — TaskFlow
|
||||
|
||||
Run a **focused** verification gate after a change or before a small PR — without replaying the entire `/build` document.
|
||||
|
||||
**Stack:** **Riverpod** / **Feature-First** / **Supabase** / ios, android, web. **Testing depth:** unit_widget. **E2E tool:** patrol. **Codegen:** freezed, json_serializable.
|
||||
|
||||
## 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: **unit_widget**)
|
||||
|
||||
- [ ] **Integration / E2E** — use **patrol** 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 **freezed, json_serializable** 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 **GitHub Actions** (github_actions): confirm the same commands the pipeline runs (analyze + tests) are green locally. Note flavor-scoped secrets for **dev, prod**.
|
||||
|
||||
---
|
||||
|
||||
## 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:** 1.0.4
|
||||
Reference in New Issue
Block a user