@atlashub/smartstack-cli 3.13.0 → 3.15.0

package/templates/skills/business-analyse/steps/step-02-decomposition.md

@@ -2,7 +2,7 @@
 name: step-02-decomposition
 description: Module decomposition - identify modules, dependency graph, topological sort, client checkpoint
 model: opus
-next_step: steps/step-03a-data.md
+next_step: steps/step-03a1-setup.md
 ---
 
 > **Context files:** `_shared.md`
@@ -38,7 +38,7 @@ ba-reader.findFeature({feature_id})
 
 IF status already "decomposed":
   Display: "Decomposition already completed. Loading next step."
-  Load: steps/step-03a-data.md
+  Load: steps/step-03a1-setup.md
   STOP
 
 ### 2. Module Identification
@@ -70,13 +70,20 @@ For each mustHave/shouldHave scope item:
 >   "priority": "must|should|could",
 >   "sortOrder": 0,
 >   "entities": ["Anticipated entity names"],
->   "estimatedComplexity": "simple|medium|complex"
+>   "estimatedComplexity": "simple|medium|complex",
+>   "anticipatedSections": [
+>     { "code": "list", "description": "Main entity list with filters", "resources": ["entity-grid", "entity-filter"] },
+>     { "code": "detail", "description": "Entity detail view", "resources": ["entity-card"] },
+>     { "code": "create", "description": "Create new entity", "resources": ["entity-form"] }
+>   ]
 > }
 > ```
 > **MANDATORY fields:** `code`, `description`, `featureType`, `dependencies`, `dependents`, `status`, `priority`, `sortOrder`, `entities`, `estimatedComplexity`
+> **OPTIONAL fields:** `anticipatedSections` (from cadrage coverageMatrix, enriched here with resources)
 > **status:** Always `"pending"` at creation (updated to `"in-progress"` → `"specified"` → `"validated"` by step-03/04)
 > **sortOrder:** Integer from topological sort (0 = foundation layer)
 > **featureJsonPath:** Set to null at creation; updated to actual path when module feature.json is created in step-03
+> **anticipatedSections:** Array of `{ code, description, resources[] }` objects. Derived from `cadrage.coverageMatrix[].anticipatedSections` aggregated per module, then refined during decomposition. These serve as starting point for step-03a1 section walkthrough.
 
 **Complexity estimation rules:**
 | Criteria | Simple | Medium | Complex |
@@ -93,14 +100,21 @@ Display the identified modules as markdown:
 ```
 ## Modules identifiés pour {application_name}
 
-| # | Module | Type | Priorité | Complexité | Entités pressenties |
-|---|--------|------|----------|------------|---------------------|
-| 1 | Customers | data-centric | must | medium | Customer, Address, Contact |
-| 2 | Products | data-centric | must | simple | Product, Category |
-| 3 | Orders | workflow | must | complex | Order, OrderLine |
-| 4 | Invoices | workflow | should | medium | Invoice, InvoiceLine, Payment |
+{language == "fr"
+  ? "**Préfixe de table :** `{metadata.tablePrefix}` — toutes les tables de cette application seront préfixées (ex: `{metadata.tablePrefix}Customers`, `{metadata.tablePrefix}Orders`)"
+  : "**Table prefix:** `{metadata.tablePrefix}` — all tables in this application will be prefixed (e.g., `{metadata.tablePrefix}Customers`, `{metadata.tablePrefix}Orders`)"}
+
+| # | Module | Type | Priorité | Complexité | Sections pressenties | Entités |
+|---|--------|------|----------|------------|---------------------|---------|
+| 1 | Customers | data-centric | must | medium | list, detail, create, edit | Customer, Address, Contact |
+| 2 | Products | data-centric | must | simple | list, detail, create | Product, Category |
+| 3 | Orders | workflow | must | complex | list, detail, create, approve, history | Order, OrderLine |
+| 4 | Invoices | workflow | should | medium | list, detail, create, export | Invoice, InvoiceLine, Payment |
 ```
 
+> **Sections are derived from:** cadrage.coverageMatrix[].anticipatedSections aggregated per module.
+> If cadrage did not provide sections, infer from module featureType using the standard section table.
+
 Ask via AskUserQuestion:
 ```
 question: "Ces modules correspondent-ils à votre vision de l'application ?"
@@ -191,12 +205,24 @@ Products ───┘
 
 ### Ordre de traitement
 
-| Ordre | Module | Dépend de | Complexité |
-|-------|--------|-----------|------------|
-| 1 | Customers | (aucune) | medium |
-| 2 | Products | (aucune) | simple |
-| 3 | Orders | Customers, Products | complex |
-| 4 | Invoices | Orders, Customers | medium |
+| Ordre | Module | Dépend de | Complexité | Sections pressenties |
+|-------|--------|-----------|------------|---------------------|
+| 1 | Customers | (aucune) | medium | list, detail, create, edit |
+| 2 | Products | (aucune) | simple | list, detail, create |
+| 3 | Orders | Customers, Products | complex | list, detail, create, approve, history |
+| 4 | Invoices | Orders, Customers | medium | list, detail, create, export |
+
+### Détail des sections et resources par module
+
+**Module : {module_name}**
+| Section | Description | Resources pressenties |
+|---------|-------------|----------------------|
+| list | {description} | {entity}-grid, {entity}-filter |
+| detail | {description} | {entity}-card, {entity}-tabs |
+| create | {description} | {entity}-form |
+| ... | ... | ... |
+
+(Repeat for each module)
 
 > Les modules seront spécifiés dans cet ordre. Chaque module sera
 > détaillé avec ses sections, entités, permissions et maquettes,
@@ -292,4 +318,4 @@ When `workflow.mode = "module"` or only 1 scope item identified:
 
 ## NEXT STEP
 
-Load: `./step-03a-data.md`
+Load: `./step-03a1-setup.md`

package/templates/skills/business-analyse/steps/step-03a-data.md

@@ -1,42 +1,16 @@
 ---
 name: step-03a-data
-description: Per-module data specification - REDIRECTS to step-03a1 (refactored into 2 sub-steps)
+description: "DEPRECATED REDIRECT - All references now point directly to step-03a1-setup.md"
 model: opus
 next_step: steps/step-03a1-setup.md
 ---
 
-> **NOTICE:** This step has been refactored into 2 sub-steps for better context management.
+> **DEPRECATED:** This file is no longer loaded in normal workflow. All step references now point directly to `step-03a1-setup.md`. This file is kept for historical reference only.
 
-# Step 3a: Specification - Data & Logic (Entry Point)
-
-This step has been divided into 2 focused sub-steps:
+# Step 3a: Specification - Data & Logic (Refactored)
 
+Refactored into 2 sub-steps:
 1. **step-03a1-setup.md** - Module setup, sections walkthrough, questionnaires, cross-refs
 2. **step-03a2-analysis.md** - Analysis section: objectives, entities, business rules, process flow
 
----
-
-## Automatic Redirect
-
-**Loading:** `./step-03a1-setup.md`
-
-The data specification process will execute in sequence:
-- step-03a1-setup → step-03a2-analysis → step-03b-ui
-
----
-
-## Why Refactored?
-
-**Before:** 468 lines in single file (exceeded 400-line recommendation)
-
-**After:** 2 focused files (~320 + ~150 lines)
-
-**Benefits:**
-- Better context management
-- Clearer separation: setup vs analysis
-- Module preparation separated from entity/logic definition
-- Reduced cognitive load per step
-
----
-
-**Proceeding to step-03a1-setup.md...**
+Flow: step-03a1-setup → step-03a2-analysis → step-03b-ui

package/templates/skills/business-analyse/steps/step-03a1-setup.md

@@ -60,7 +60,7 @@ ba-reader.readApplicationContext({feature_id})
 
 IF module already specified (status = "specified" in master):
   Increment currentModuleIndex, re-check
-  IF all modules specified → Load step-04-consolidation.md, STOP
+  IF all modules specified → Load step-04a-collect.md, STOP
 
 ### 1b. Cache Warming for Module Loop (FIRST MODULE ONLY)
 
@@ -74,7 +74,7 @@ IF currentModuleIndex === 0:
     "~/.claude/skills/business-analyse/references/spec-auto-inference.md",
     "~/.claude/skills/business-analyse/references/ui-resource-cards.md",
     "~/.claude/skills/business-analyse/references/ui-dashboard-spec.md",
-    "~/.claude/skills/business-analyse/references/cadrage-vibe-coding.md"
+    "~/.claude/skills/business-analyse/references/cadrage-pre-analysis.md"
   ];
 
   for (const file of moduleRefs) {
@@ -349,6 +349,45 @@ options:
     description: "Pas de référence à {completedModule}"
 ```
 
+#### 5-bis. Unresolved Entity Dependencies (New Module Detection)
+
+> **When an entity reference is detected that does NOT belong to any completed or planned module, apply the Entity Sourcing Pattern from step-01-cadrage (section 4d-bis).**
+
+For each entity referenced by {currentModule} that is NOT covered by any existing/planned module:
+
+```
+question: "{language == 'fr'
+  ? 'Les {entity_plural} référencés par {currentModule} ne font partie d\'aucun module. Comment les gérer ?'
+  : '{entity_plural} referenced by {currentModule} are not part of any module. How should they be managed?'}"
+header: "{entity_name}"
+options:
+  - label: "{language == 'fr' ? 'Dans ce module' : 'In this module'}"
+    description: "{language == 'fr'
+      ? 'Gérer les {entity_plural} comme une section/entité de {currentModule}'
+      : 'Manage {entity_plural} as a section/entity of {currentModule}'}"
+  - label: "{language == 'fr' ? 'Nouveau module dédié' : 'New dedicated module'}"
+    description: "{language == 'fr'
+      ? 'Créer un module complet avec CRUD, permissions et navigation'
+      : 'Create a full module with CRUD, permissions and navigation'}"
+  - label: "{language == 'fr' ? 'Système externe' : 'External system'}"
+    description: "{language == 'fr'
+      ? 'Import ou API depuis un autre système'
+      : 'Import or API from another system'}"
+  - label: "{language == 'fr' ? 'Liste de référence' : 'Reference list'}"
+    description: "{language == 'fr'
+      ? 'Table de lookup configurable par l\'admin'
+      : 'Admin-configurable lookup table'}"
+```
+
+**IF "Nouveau module dédié" is selected:**
+1. Add new module to master `modules[]` via ba-writer (status: "pending", sortOrder: after current module)
+2. Update dependency graph: current module depends on the new module
+3. **WARNING:** The new module will need specification AFTER the current one. Display:
+   ```
+   "⚠ Nouveau module '{entity_name}' ajouté. Il sera spécifié après {currentModule}."
+   ```
+4. Update `metadata.workflow.moduleOrder` to include the new module (inserted after its dependents)
+
 ---
 
 ## NEXT STEP

package/templates/skills/business-analyse/steps/step-03b-ui.md

@@ -12,7 +12,7 @@ next_step: steps/step-03c-compile.md
 ## MANDATORY EXECUTION RULES
 
 - ALWAYS use ULTRATHINK mode
-- This step is EXECUTED ONCE PER MODULE, after step-03a-data.md
+- This step is EXECUTED ONCE PER MODULE, after step-03a1-setup.md and step-03a2-analysis.md
 - **WIREFRAME RULE:** Every section MUST have a wireframe in `specification.uiWireframes[]`. No section without a validated mockup.
 - **ID NAMING RULE (MANDATORY, NO EXCEPTION):**
   All IDs MUST include a module prefix to guarantee application-wide uniqueness.
@@ -136,7 +136,17 @@ See [references/ui-resource-cards.md](../references/ui-resource-cards.md) for ex
 > **BLOCKING RULE:** Every section MUST have a wireframe. No section proceeds to entity definition (step 6) without a validated mockup stored in `specification.uiWireframes[]`.
 > **HTML INTEGRATION:** These wireframes are also rendered in the interactive HTML document (`ba-interactive.html`) deployed at handoff. The client can review and annotate mockups directly in their browser.
 
-For each confirmed section, generate an ASCII mockup and validate with client:
+**Procedural sequence (MANDATORY — follow in exact order):**
+
+1. **Generate** an ASCII mockup for each confirmed section
+2. **Display** each mockup in the conversation output with a markdown header:
+   ```
+   ### {SectionName} — Wireframe
+   ```
+   followed by the ASCII art in a code block. **ALL mockups MUST be visible text in the conversation.**
+3. **Only THEN** call `AskUserQuestion` to ask the client to validate the displayed mockups (batch 2-3 at once if possible)
+
+> **BLOCKING RULE:** You MUST NOT call AskUserQuestion for wireframe validation until ALL mockups are displayed as visible text in the conversation. The client cannot validate what they cannot see.
 
 Example for a list section:
 
@@ -160,8 +170,6 @@ See [references/ui-resource-cards.md](../references/ui-resource-cards.md) for ex
 **REQUIRED fields:** `screen`, `mockup`, `elements`, `section`, `componentMapping`, `layout` are ALL mandatory.
 A wireframe without `componentMapping` or `layout` will FAIL validation in step 9.
 
-Ask client to validate each mockup via AskUserQuestion (batch 2-3 mockups at once if possible).
-
 > **IF client rejects a mockup:** Revise and re-propose until validated. Do NOT proceed without client approval on the layout.
 
 ### 3b-bis. Wireframe-to-Component Mapping
@@ -234,13 +242,14 @@ See [references/ui-dashboard-spec.md](../references/ui-dashboard-spec.md) for th
 
 Before proceeding to step-03c-compile.md, VERIFY:
 
-1. **Wireframes exist for all sections** in `specification.uiWireframes[]`
-2. **All wireframes have componentMapping** with smarter mapping rules
-3. **All wireframes have layout** with regions and resourceRef references
-4. **All resource references** in layout.regions[].components[].resourceRef exist in sections[].resources[]
-5. **State machines defined** (if module has status fields) in `specification.lifeCycles[]`
-6. **Form field completeness** — SmartForm fields[] covers ALL entity attributes except system/audit fields
-7. **Navigation entries for all sections** — Every section (including dashboard) has a corresponding entry in `specification.navigation.entries[]`
+1. **Wireframes displayed and validated** — ALL wireframes were output as visible ASCII art in the conversation AND validated by the client via AskUserQuestion
+2. **Wireframes exist for all sections** in `specification.uiWireframes[]`
+3. **All wireframes have componentMapping** with smarter mapping rules
+4. **All wireframes have layout** with regions and resourceRef references
+5. **All resource references** in layout.regions[].components[].resourceRef exist in sections[].resources[]
+6. **State machines defined** (if module has status fields) in `specification.lifeCycles[]`
+7. **Form field completeness** — SmartForm fields[] covers ALL entity attributes except system/audit fields
+8. **Navigation entries for all sections** — Every section (including dashboard) has a corresponding entry in `specification.navigation.entries[]`
 
 **IF any check fails → FIX before proceeding.** Do NOT load step-03c-compile with incomplete data.
 

package/templates/skills/business-analyse/steps/step-03d-validate.md

@@ -2,7 +2,7 @@
 name: step-03d-validate
 description: Per-module validation, write feature.json, incremental HTML deploy, loop decision
 model: sonnet
-next_step: steps/step-03a-data.md OR steps/step-04-consolidation.md (conditional)
+next_step: steps/step-03a1-setup.md OR steps/step-04a-collect.md (conditional)
 ---
 
 > **Context files:** `_shared.md` | `_module-loop.md`
@@ -279,12 +279,12 @@ ba-writer.advanceModuleLoop({feature_id})
 
 IF currentModuleIndex < moduleOrder.length:
   Display: "→ Module suivant: {nextModule} ({currentModuleIndex + 1}/{total})"
-  Load: steps/step-03a-data.md
+  Load: steps/step-03a1-setup.md
 
 IF currentModuleIndex >= moduleOrder.length:
   Display: "═══ Tous les modules spécifiés! Passage à la consolidation... ═══"
   ba-writer.updateStatus({feature_id}, "specified")
-  Load: steps/step-04-consolidation.md
+  Load: steps/step-04a-collect.md
 ```
 
 ---
@@ -308,7 +308,7 @@ When only 1 module in moduleOrder:
 
 - Same full validation flow
 - Skip cross-module references (section 5)
-- After validation → direct to step-04-consolidation.md (auto-consolidation)
+- After validation → direct to step-04a-collect.md (auto-consolidation)
 
 ---
 
@@ -372,5 +372,5 @@ Read metadata.workflow.currentModule
 
 Conditional:
 
-- IF modules remaining → Load `steps/step-03a-data.md`
-- IF all modules done → Load `steps/step-04-consolidation.md`
+- IF modules remaining → Load `steps/step-03a1-setup.md`
+- IF all modules done → Load `steps/step-04a-collect.md`

package/templates/skills/business-analyse/steps/step-04-consolidation.md

@@ -1,43 +1,17 @@
 ---
 name: step-04-consolidation
-description: Cross-module consolidation - REDIRECTS to step-04a (refactored into 3 sub-steps)
+description: "DEPRECATED REDIRECT - All references now point directly to step-04a-collect.md"
 model: opus
 next_step: steps/step-04a-collect.md
 ---
 
-> **NOTICE:** This step has been refactored into 3 sub-steps for better context management.
+> **DEPRECATED:** This file is no longer loaded in normal workflow. All step references now point directly to `step-04a-collect.md`. This file is kept for historical reference only.
 
-# Step 4: Consolidation (Entry Point)
-
-This step has been divided into 3 focused sub-steps:
+# Step 4: Consolidation (Refactored)
 
+Refactored into 3 sub-steps:
 1. **step-04a-collect.md** - Collect module summaries and cross-module interactions
 2. **step-04b-analyze.md** - Analyze permissions, validation, E2E flows, and risks
 3. **step-04c-decide.md** - Obtain final approval and write consolidation
 
----
-
-## Automatic Redirect
-
-**Loading:** `./step-04a-collect.md`
-
-The consolidation process will execute in sequence:
-- step-04a-collect → step-04b-analyze → step-04c-decide → step-05a-handoff
-
----
-
-## Why Refactored?
-
-**Before:** 628 lines in single file (exceeded 400-line recommendation)
-
-**After:** 3 focused files (~200-280 lines each)
-
-**Benefits:**
-- Better context management
-- Clearer separation of concerns (collect → analyze → decide)
-- Easier to resume from specific consolidation phase
-- Reduced cognitive load per step
-
----
-
-**Proceeding to step-04a-collect.md...**
+Flow: step-04a-collect → step-04b-analyze → step-04c-decide → step-05a-handoff

package/templates/skills/business-analyse/steps/step-04c-decide.md

@@ -37,7 +37,7 @@ options:
 ```
 
 IF "Réviser un module":
-  Ask which module → set currentModuleIndex to that module → load step-03a-data.md
+  Ask which module → set currentModuleIndex to that module → load step-03a1-setup.md
 
 IF "Modifier les interactions":
   Re-enter step-04a-collect.md (sections 2-4)

package/templates/skills/business-analyse/steps/step-05a-handoff.md

@@ -36,7 +36,7 @@ ba-reader.findFeature({feature_id})
 → Check status = "consolidated"
 ```
 
-**IF** status ≠ "consolidated" → **STOP**. Return to step-04-consolidation.md.
+**IF** status ≠ "consolidated" → **STOP**. Return to step-04a-collect.md.
 
 Display validation summary:
 

package/templates/skills/business-analyse/steps/step-05b-deploy.md

@@ -19,7 +19,7 @@ next_step: steps/step-05c-ralph-readiness.md
 - **ALWAYS** follow references/html-data-mapping.md EXACTLY for FEATURE_DATA and EMBEDDED_ARTIFACTS mapping
 - **FEATURE_DATA.moduleSpecs MUST be populated for EACH module** — empty moduleSpecs = BROKEN specification tabs
 - **FEATURE_DATA.cadrage.scope must use HTML keys** (vital/important/optional/excluded) NOT feature.json keys (mustHave/shouldHave/couldHave/outOfScope)
-- **FEATURE_DATA.metadata.vibeCoding must be set** from master.metadata.vibeCoding (controls section visibility)
+- **FEATURE_DATA.metadata.analysisMode must be set** from master.metadata.analysisMode (always "interactive")
 - **NEVER leave FEATURE_DATA or EMBEDDED_ARTIFACTS empty or partial**
 
 ## YOUR TASK
@@ -214,7 +214,7 @@ IF ANY category shows FAIL → **STOP AND RE-RUN `ss derive-prd`**. DO NOT proce
 - FEATURE_DATA must be pre-populated with ALL analysis data (empty data = BUG)
 - FEATURE_DATA.**moduleSpecs** MUST be populated for EACH module (use cases, business rules, entities, permissions) — empty moduleSpecs = BROKEN specification tabs
 - FEATURE_DATA.**cadrage.scope** must use HTML keys (vital/important/optional/excluded) NOT feature.json keys (mustHave/shouldHave/couldHave/outOfScope)
-- FEATURE_DATA.**metadata.vibeCoding** must be set from `master.metadata.vibeCoding` (controls section visibility)
+- FEATURE_DATA.**metadata.analysisMode** must be set from `master.metadata.analysisMode` (always "interactive")
 - EMBEDDED_ARTIFACTS contains wireframes, E2E diagrams, dependency graph
 - Both objects are serialized as JSON with 2-space indentation
 - All data mapped from master and module feature.json files — follow `html-data-mapping.md` EXACTLY
@@ -233,7 +233,7 @@ See [references/deploy-data-build.md](../references/deploy-data-build.md) for:
 **Critical reminders:**
 - FEATURE_DATA.**moduleSpecs** MUST have ONE entry per module (empty = BUG)
 - FEATURE_DATA.**cadrage.scope** converts `mustHave→vital`, `shouldHave→important`, `couldHave→optional`, `outOfScope→excluded`
-- FEATURE_DATA.**metadata.vibeCoding** from `master.metadata.vibeCoding`
+- FEATURE_DATA.**metadata.analysisMode** from `master.metadata.analysisMode`
 - Also reference `references/html-data-mapping.md` for the full mapping spec
 
 ---

package/templates/skills/business-analyse/steps/step-05c-ralph-readiness.md

@@ -203,7 +203,7 @@ Total: 4 cross-module references, all resolvable
 
 **IF ANY reference is unresolvable:**
 - **BLOCKING ERROR:** List broken references with module and field names
-- **FIX:** Return to step-03a-data.md for affected modules to fix entity references
+- **FIX:** Return to step-03a1-setup.md for affected modules to fix entity references
 - **STOP** - do not proceed to next check
 
 ---

package/templates/skills/business-analyse/templates/tpl-frd.md

@@ -1,7 +1,7 @@
 # Template Functional Requirements Document
 
 > **Usage:** Template for 3-functional-specification.md
-> **Loaded in:** step-03a-data.md
+> **Loaded in:** step-03a1-setup.md
 
 ---
 

package/templates/skills/efcore/steps/shared/step-00-init.md

@@ -16,6 +16,61 @@ Detect EF Core project structure, identify DbContext (Core vs Extensions), and l
 
 ## EXECUTION SEQUENCE:
 
+### 0. Ensure dotnet ef Available (Platform-Aware)
+
+> **CRITICAL:** On Windows (Git Bash, MSYS2), `dotnet ef` may not be on the shell PATH
+> even though it's installed. This step fixes PATH before any EF Core command.
+
+```bash
+ensure_dotnet_ef() {
+  # Quick check: already available?
+  if dotnet ef --version &>/dev/null; then
+    DOTNET_EF_VERSION=$(dotnet ef --version 2>/dev/null)
+    echo "dotnet-ef: $DOTNET_EF_VERSION"
+    return 0
+  fi
+
+  echo "dotnet-ef not on PATH, attempting platform-aware fix..."
+
+  # Try all known .NET global tools locations
+  # - $USERPROFILE/.dotnet/tools  → Windows via Git Bash (USERPROFILE=C:\Users\xxx)
+  # - $HOME/.dotnet/tools         → Linux/macOS or Git Bash fallback
+  # - $LOCALAPPDATA/Microsoft/dotnet/tools → Windows alternate location
+  for TOOLS_DIR in \
+    "$USERPROFILE/.dotnet/tools" \
+    "$HOME/.dotnet/tools" \
+    "$LOCALAPPDATA/Microsoft/dotnet/tools"; do
+    if [ -n "$TOOLS_DIR" ] && [ -d "$TOOLS_DIR" ]; then
+      export PATH="$TOOLS_DIR:$PATH"
+      echo "  PATH += $TOOLS_DIR"
+    fi
+  done
+
+  # Verify after PATH fix
+  if dotnet ef --version &>/dev/null; then
+    DOTNET_EF_VERSION=$(dotnet ef --version 2>/dev/null)
+    echo "dotnet-ef: $DOTNET_EF_VERSION (found after PATH fix)"
+    return 0
+  fi
+
+  echo "ERROR: dotnet-ef not available"
+  echo "Install with: dotnet tool install --global dotnet-ef"
+  echo ""
+  echo "If installed but not found, check:"
+  echo "  Windows: %USERPROFILE%\\.dotnet\\tools must be in PATH"
+  echo "  Linux:   ~/.dotnet/tools must be in PATH"
+  exit 1
+}
+
+ensure_dotnet_ef
+```
+
+**IMPORTANT — WSL pitfall:**
+If the shell resolves `$HOME` to `/home/{user}` (WSL path) instead of `/c/Users/{user}` (Git Bash),
+the .NET SDK may not be found even if `dotnet-ef` is. Use `$USERPROFILE` first on Windows.
+
+---
+
 ### 1. Detect EF Core Project
 
 ```bash

package/templates/skills/ralph-loop/SKILL.md

@@ -115,6 +115,7 @@ LOAD → GENERATE → COMPILE → TEST → [FAIL?] → FIX → RE-TEST → [PASS
 | `references/category-rules.md` | Step-02 and compact loop (execution rules per category) |
 | `references/compact-loop.md` | Step-04 section 5 (inline execution after first iteration) |
 | `references/core-seed-data.md` | Infrastructure task with seed data keywords |
+| `references/error-classification.md` | Build failure in compact loop or validation (error diagnosis) |
 | `references/team-orchestration.md` | Step-00 when multi-module detected (2+ PRDs) |
 </step_files>