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>

docs/superpowers/specs/2026-05-14-build-skill-design.md

@@ -205,6 +205,14 @@ The `/build` skill orchestrates existing skills internally:
 - Invokes `/generate-api-client` if `api_docs.format != none` and feature needs API (Phase 2)
 - References `/deploy` checklist for flavor-scoped secret handling (Phase 7)
 
+Generated alongside `/build` (same `cursor_gen` bundle) for lifecycle support:
+
+- **`/debug`** (`debug-issue` skill) — structured BugReport + evidence before fixes; use when Phase 6 checks fail with unclear errors or weak reproduction.
+- **`/verify`** (`verify-change` skill) — pasted-evidence gate for tests/analyze/hooks without walking the full seven-phase build doc; use for small PRs or post-fix sanity checks.
+- **`/explain`** (`explain-code` skill) — read-only walkthrough of code paths; use when research needs human answers about runtime or native behavior before implementation.
+
+The generated `build` skill template also cross-links **Phase 3** (TDD loop) and **Phase 6** (verification failures) to **`/debug`** and **`/verify`** so agents escalate without re-reading the full seven-phase doc.
+
 ---
 
 ## 9. Rules Applied Every Phase

flutter-cursor-templates/generator/src/resolver.dart

@@ -73,6 +73,9 @@ class Resolver {
       'skills/scaffold-screen',
       'skills/generate-tests',
       'skills/build',
+      'skills/debug-issue',
+      'skills/verify-change',
+      'skills/explain-code',
     ]);
     if (brief.apiDocsFormat != 'none') files.add('skills/generate-api-client');
     if (brief.flavors.length > 1)      files.add('skills/create-flavor');
@@ -127,6 +130,9 @@ class Resolver {
     if (key.contains('migration'))      return 'state_management is GetX — migration guidance included';
     if (key.contains('security-agent')) return 'scale: ${brief.scale} or auth is configured';
     if (key == 'skills/build')           return 'Always included — universal TDD-first feature implementation command';
+    if (key == 'skills/debug-issue')     return 'Always included — structured bug triage and evidence-first debugging';
+    if (key == 'skills/verify-change')  return 'Always included — pre-PR verification checklist without full /build lifecycle';
+    if (key == 'skills/explain-code')    return 'Always included — explain-only walkthrough of code paths and stack behavior';
     if (key.contains('api-client'))     return 'api_docs.format is set';
     if (key.contains('realtime'))       return 'features.special contains realtime';
     if (key.startsWith('root/'))        return 'Repo-level companion files';

flutter-cursor-templates/generator/templates/root/AGENTS.md.tmpl

@@ -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:** `{{PACKAGE_ID}}`
+- **Slash skills** (see `.cursor/skills/`): `/build`, `/debug`, `/verify`, `/explain`

flutter-cursor-templates/generator/templates/skills/build/SKILL.md.tmpl

@@ -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.
 
 ---

flutter-cursor-templates/generator/templates/skills/debug-issue/SKILL.md.tmpl

@@ -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}}

flutter-cursor-templates/generator/templates/skills/explain-code/SKILL.md.tmpl

@@ -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}}

flutter-cursor-templates/generator/templates/skills/verify-change/SKILL.md.tmpl

@@ -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}}

flutter-cursor-templates/generator/test/generator_test.dart

@@ -3,103 +3,18 @@
 
 import 'dart:io';
 import 'package:test/test.dart';
+import 'golden_briefs.dart';
 import '../src/resolver.dart';
 import '../src/renderer.dart';
 import '../src/validator.dart';
 import '../src/models.dart';
 
-// ─── Test fixtures ─────────────────────────────────────────────────────────
-
-final _blocCleanBrief = ProjectBrief(
-  projectName: 'TestApp',
-  packageId: 'com.test.testapp',
-  description: 'Test app for golden tests',
-  scale: 'medium',
-  stateManagement: 'bloc',
-  routing: 'gorouter',
-  architecture: 'clean',
-  backends: ['firebase'],
-  auth: 'firebase_auth',
-  platforms: ['ios', 'android'],
-  codegenTools: ['freezed'],
-  flavors: ['dev', 'prod'],
-  cicd: 'github_actions',
-  testingDepth: 'unit_widget',
-  e2eTool: 'patrol',
-  designSource: 'none',
-  figmaUrl: '',
-  apiDocsFormat: 'none',
-  apiDocsPath: '',
-  referenceRepos: [],
-  localPaths: [],
-  featureModules: ['auth', 'home', 'products'],
-  specialFeatures: [],
-  i18nEnabled: false,
-  locales: ['en'],
-);
-
-final _riverpodFFBrief = ProjectBrief(
-  projectName: 'TaskFlow',
-  packageId: 'com.test.taskflow',
-  description: 'Task management app',
-  scale: 'small',
-  stateManagement: 'riverpod',
-  routing: 'gorouter',
-  architecture: 'feature_first',
-  backends: ['supabase'],
-  auth: 'supabase_auth',
-  platforms: ['ios', 'android', 'web'],
-  codegenTools: ['freezed', 'json_serializable'],
-  flavors: ['dev', 'prod'],
-  cicd: 'github_actions',
-  testingDepth: 'unit_widget',
-  e2eTool: 'patrol',
-  designSource: 'none',
-  figmaUrl: '',
-  apiDocsFormat: 'none',
-  apiDocsPath: '',
-  referenceRepos: [],
-  localPaths: [],
-  featureModules: ['auth', 'tasks', 'profile'],
-  specialFeatures: [],
-  i18nEnabled: true,
-  locales: ['en', 'fr'],
-);
-
-final _getxMvcBrief = ProjectBrief(
-  projectName: 'LegacyApp',
-  packageId: 'com.test.legacy',
-  description: 'Legacy GetX app',
-  scale: 'medium',
-  stateManagement: 'getx',
-  routing: 'getx_nav',
-  architecture: 'mvc',
-  backends: ['rest'],
-  auth: 'jwt_rest',
-  platforms: ['ios', 'android'],
-  codegenTools: [],
-  flavors: ['dev', 'prod'],
-  cicd: 'codemagic',
-  testingDepth: 'unit_widget',
-  e2eTool: 'patrol',
-  designSource: 'none',
-  figmaUrl: '',
-  apiDocsFormat: 'openapi',
-  apiDocsPath: 'docs/api.yaml',
-  referenceRepos: [],
-  localPaths: [],
-  featureModules: ['auth', 'dashboard'],
-  specialFeatures: [],
-  i18nEnabled: false,
-  locales: ['en'],
-);
-
 void main() {
 // ─── Resolver tests ─────────────────────────────────────────────────────────
 
   group('Resolver', () {
     test('BLoC + Clean resolves correct files', () {
-      final files = Resolver.resolve(_blocCleanBrief);
+      final files = Resolver.resolve(kBlocCleanFirebaseBrief);
 
       // Universal — always present
       expect(files, contains('rules/universal/flutter-core'));
@@ -147,7 +62,7 @@ void main() {
     });
 
     test('Riverpod + Feature-First + Web resolves web platform template', () {
-      final files = Resolver.resolve(_riverpodFFBrief);
+      final files = Resolver.resolve(kRiverpodFfSupabaseBrief);
       expect(files, contains('rules/platform/platform-web'));
       expect(files, contains('rules/state-management/riverpod'));
       expect(files, contains('rules/architecture/feature_first'));
@@ -158,7 +73,7 @@ void main() {
     });
 
     test('GetX + MVC includes migration-agent', () {
-      final files = Resolver.resolve(_getxMvcBrief);
+      final files = Resolver.resolve(kGetxMvcRestBrief);
       expect(files, contains('agents/migration-agent'));
       expect(files, contains('rules/state-management/getx'));
       expect(files, contains('rules/architecture/mvc'));
@@ -171,7 +86,7 @@ void main() {
     });
 
     test('Codegen stack includes Cursor hooks templates', () {
-      final files = Resolver.resolve(_blocCleanBrief);
+      final files = Resolver.resolve(kBlocCleanFirebaseBrief);
       expect(files, contains('hooks/hooks-json'));
       expect(files, contains('hooks/arch-guard'));
     });
@@ -241,17 +156,26 @@ void main() {
     });
 
     test('No duplicate files in resolved list', () {
-      final files = Resolver.resolve(_blocCleanBrief);
+      final files = Resolver.resolve(kBlocCleanFirebaseBrief);
       final unique = files.toSet();
       expect(files.length, equals(unique.length),
           reason: 'Duplicate template files detected');
     });
 
-    test('build skill always included in resolved list', () {
+    test('Universal slash skills always in resolved list', () {
-      expect(Resolver.resolve(_blocCleanBrief), contains('skills/build'));
+      const universalSkills = [
-      expect(Resolver.resolve(_riverpodFFBrief), contains('skills/build'));
+        'skills/build',
-      expect(Resolver.resolve(_getxMvcBrief), contains('skills/build'));
+        'skills/debug-issue',
+        'skills/verify-change',
+        'skills/explain-code',
+      ];
+      for (final skill in universalSkills) {
+        expect(Resolver.resolve(kBlocCleanFirebaseBrief), contains(skill));
+        expect(Resolver.resolve(kRiverpodFfSupabaseBrief), contains(skill));
+        expect(Resolver.resolve(kGetxMvcRestBrief), contains(skill));
+      }
     });
+
   });
 
 // ─── Renderer / placeholder tests ───────────────────────────────────────────
@@ -283,8 +207,8 @@ void main() {
       }
 
       final rendered = await Renderer.render(
-        brief: _blocCleanBrief,
+        brief: kBlocCleanFirebaseBrief,
-        templateFiles: Resolver.resolve(_blocCleanBrief),
+        templateFiles: Resolver.resolve(kBlocCleanFirebaseBrief),
         templateSrc: templateDir,
       );
 
@@ -309,7 +233,7 @@ void main() {
       }
 
       final rendered = await Renderer.render(
-        brief: _blocCleanBrief,
+        brief: kBlocCleanFirebaseBrief,
         templateFiles: ['hooks/arch-guard'],
         templateSrc: templateDir,
       );
@@ -327,7 +251,7 @@ void main() {
 
   group('Validator', () {
     test('Valid brief passes validation', () async {
-      final result = await Validator.validate(_blocCleanBrief);
+      final result = await Validator.validate(kBlocCleanFirebaseBrief);
       expect(result.isValid, isTrue);
       expect(result.errors, isEmpty);
     });
@@ -410,8 +334,8 @@ void main() {
       }
 
       final rendered = await Renderer.render(
-        brief: _blocCleanBrief,
+        brief: kBlocCleanFirebaseBrief,
-        templateFiles: Resolver.resolve(_blocCleanBrief),
+        templateFiles: Resolver.resolve(kBlocCleanFirebaseBrief),
         templateSrc: templateDir,
       );
 
@@ -439,8 +363,8 @@ void main() {
         return;
       }
       final rendered = await Renderer.render(
-        brief: _riverpodFFBrief,
+        brief: kRiverpodFfSupabaseBrief,
-        templateFiles: Resolver.resolve(_riverpodFFBrief),
+        templateFiles: Resolver.resolve(kRiverpodFfSupabaseBrief),
         templateSrc: templateDir,
       );
       await _compareGoldens('test/golden/riverpod-ff-supabase', rendered);
@@ -453,8 +377,8 @@ void main() {
         return;
       }
       final rendered = await Renderer.render(
-        brief: _getxMvcBrief,
+        brief: kGetxMvcRestBrief,
-        templateFiles: Resolver.resolve(_getxMvcBrief),
+        templateFiles: Resolver.resolve(kGetxMvcRestBrief),
         templateSrc: templateDir,
       );
       await _compareGoldens('test/golden/getx-mvc-rest', rendered);

flutter-cursor-templates/generator/test/golden/bloc-clean-firebase/__root__/AGENTS.md

@@ -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.testapp`
+- **Slash skills** (see `.cursor/skills/`): `/build`, `/debug`, `/verify`, `/explain`

flutter-cursor-templates/generator/test/golden/bloc-clean-firebase/skills/build/SKILL.md

@@ -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
 
@@ -374,6 +375,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
@@ -506,6 +509,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.
 
 ---

flutter-cursor-templates/generator/test/golden/bloc-clean-firebase/skills/debug-issue/SKILL.md

@@ -0,0 +1,89 @@
+---
+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.4

flutter-cursor-templates/generator/test/golden/bloc-clean-firebase/skills/explain-code/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: Explain code
+description: Explain what code does without editing it. Use /explain with a path or symbol; covers BLoC / Cubit state, Firebase I/O, routing GoRouter, and failure modes. Ask when facts are not in the repo.
+---
+
+# Explain — TestApp
+
+Explain **what the code is doing** — **do not** change production code unless the user explicitly asks for a fix.
+
+**Stack:** **BLoC / Cubit** / **Clean Architecture** / **GoRouter** / **Firebase** / platforms: ios, android. Package: `com.test.testapp`.
+
+## 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 (**TestApp** — Test app for golden tests).
+
+### Public API
+
+Surface area: public classes/methods, constructors, and what callers are expected to pass. Note codegen involvement when **freezed** 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 **BLoC / Cubit** (bloc). Mention async work, listeners, and disposal. Reference **- 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** if layering is unclear.
+
+### I/O and backends
+
+Network, local storage, or platform channels touching **Firebase** (and **Firebase Auth** where auth applies: firebase_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, auth edge cases.
+
+### Suggested tests
+
+Ideas aligned with **unit_widget** and **patrol**; for **BLoC / Cubit**, prefer patterns like:
+
+```
+blocTest<MyCubit, MyState>(description, build: () => MyCubit(), act: (c) => c.method(), expect: () => [MyState()])
+```
+
+### 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, home, products; special features: .
+- **Scale:** medium; i18n locales: en (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

flutter-cursor-templates/generator/test/golden/bloc-clean-firebase/skills/verify-change/SKILL.md

@@ -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 — TestApp
+
+Run a **focused** verification gate after a change or before a small PR — without replaying the entire `/build` document.
+
+**Stack:** **BLoC / Cubit** / **Clean Architecture** / **Firebase** / ios, android. **Testing depth:** unit_widget. **E2E tool:** patrol. **Codegen:** freezed.
+
+## 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** 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

flutter-cursor-templates/generator/test/golden/getx-mvc-rest/__root__/AGENTS.md

@@ -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.legacy`
+- **Slash skills** (see `.cursor/skills/`): `/build`, `/debug`, `/verify`, `/explain`

flutter-cursor-templates/generator/test/golden/getx-mvc-rest/skills/build/SKILL.md

@@ -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.
 
 ---

flutter-cursor-templates/generator/test/golden/getx-mvc-rest/skills/debug-issue/SKILL.md

@@ -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 GetX / MVC / REST API / ios, android.
+---
+
+# Debug — LegacyApp
+
+Triage failures (tests, CI, runtime, or build) **without** jumping to fixes. Stay in hypothesis-and-evidence mode until root cause is stated.
+
+**Stack context:** **GetX** / **MVC** / **REST API** / platforms: ios, android. Flavors: dev, prod. Codegen: none.
+
+## 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: **none**. 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 **MVC**:
+- View (Widget) MUST NOT contain business logic
+- Controller MUST NOT import Flutter widgets directly
+- Model MUST be plain Dart, no framework dependencies
+- Always consider: `.cursor/rules/flutter-core.mdc`, `.cursor/rules/security-standards.mdc`, `.cursor/rules/project-context.mdc`, and state-management rules for **GetX**.
+
+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

flutter-cursor-templates/generator/test/golden/getx-mvc-rest/skills/explain-code/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: Explain code
+description: Explain what code does without editing it. Use /explain with a path or symbol; covers GetX state, REST API I/O, routing GetX Navigation, and failure modes. Ask when facts are not in the repo.
+---
+
+# Explain — LegacyApp
+
+Explain **what the code is doing** — **do not** change production code unless the user explicitly asks for a fix.
+
+**Stack:** **GetX** / **MVC** / **GetX Navigation** / **REST API** / platforms: ios, android. Package: `com.test.legacy`.
+
+## 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 (**LegacyApp** — Legacy GetX app).
+
+### Public API
+
+Surface area: public classes/methods, constructors, and what callers are expected to pass. Note codegen involvement when **none** 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 **GetX Navigation** where relevant.
+
+### State and side effects
+
+How state is held and updated for **GetX** (getx). Mention async work, listeners, and disposal. Reference **- View (Widget) MUST NOT contain business logic
+- Controller MUST NOT import Flutter widgets directly
+- Model MUST be plain Dart, no framework dependencies** if layering is unclear.
+
+### I/O and backends
+
+Network, local storage, or platform channels touching **REST API** (and **JWT / REST Auth** where auth applies: jwt_rest). 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, auth edge cases.
+
+### Suggested tests
+
+Ideas aligned with **unit_widget** and **patrol**; for **GetX**, prefer patterns like:
+
+```
+Get.put(MyController()); final ctrl = Get.find<MyController>(); expect(ctrl.value, expected);
+```
+
+### 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, dashboard; special features: .
+- **Scale:** medium; i18n locales: en (when explaining localization).
+- **Design:** none; Figma URL: .
+- **API docs format:** openapi (path: docs/api.yaml).
+- **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

flutter-cursor-templates/generator/test/golden/getx-mvc-rest/skills/verify-change/SKILL.md

@@ -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 — LegacyApp
+
+Run a **focused** verification gate after a change or before a small PR — without replaying the entire `/build` document.
+
+**Stack:** **GetX** / **MVC** / **REST API** / ios, android. **Testing depth:** unit_widget. **E2E tool:** patrol. **Codegen:** none.
+
+## 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 **none** 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 **Codemagic** (codemagic): 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

flutter-cursor-templates/generator/test/golden/riverpod-ff-supabase/__root__/AGENTS.md

@@ -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`

flutter-cursor-templates/generator/test/golden/riverpod-ff-supabase/skills/build/SKILL.md

@@ -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.
 
 ---

flutter-cursor-templates/generator/test/golden/riverpod-ff-supabase/skills/debug-issue/SKILL.md

@@ -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

flutter-cursor-templates/generator/test/golden/riverpod-ff-supabase/skills/explain-code/SKILL.md

@@ -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

flutter-cursor-templates/generator/test/golden/riverpod-ff-supabase/skills/verify-change/SKILL.md

@@ -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

flutter-cursor-templates/templates/root/AGENTS.md.tmpl

@@ -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:** `{{PACKAGE_ID}}`
+- **Slash skills** (see `.cursor/skills/`): `/build`, `/debug`, `/verify`, `/explain`

flutter-cursor-templates/templates/skills/build/SKILL.md.tmpl

@@ -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.
 
 ---

flutter-cursor-templates/templates/skills/debug-issue/SKILL.md.tmpl

@@ -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}}

flutter-cursor-templates/templates/skills/explain-code/SKILL.md.tmpl

@@ -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}}

flutter-cursor-templates/templates/skills/verify-change/SKILL.md.tmpl

@@ -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}}