@atlashub/smartstack-cli 3.10.0 → 3.12.0

package/templates/skills/business-analyse/references/validate-incremental-html.md

@@ -33,23 +33,66 @@ Follow step-05 section 9d "Step 2: Build FEATURE_DATA object" for the complete m
 - `consolidation` → empty `{ interactions: [], e2eFlows: [] }` (not yet consolidated)
 - `handoff` → empty `{}` (not yet handed off)
 
-### Step 3: Replace Placeholders in Template
+### Step 3: Build EMBEDDED_ARTIFACTS Object
+
+> **CRITICAL: Without EMBEDDED_ARTIFACTS, the Maquettes tab will show EMPTY mockups.**
+> Use the EXACT SAME mapping defined in references/deploy-data-build.md and references/html-data-mapping.md.
+
+Build EMBEDDED_ARTIFACTS with wireframes for completed modules only:
+
+```javascript
+const EMBEDDED_ARTIFACTS = {
+  wireframes: {
+    // FOR EACH completed module: extract wireframes with RENAMED fields
+    [moduleCode]: moduleFeature.specification.uiWireframes.map(wf => ({
+      screen: wf.screen,
+      section: wf.section,
+      format: wf.mockupFormat || "ascii",   // RENAME: mockupFormat → format
+      content: wf.mockup,                    // RENAME: mockup → content
+      description: wf.description || "",
+      elements: wf.elements || [],
+      actions: wf.actions || [],
+      componentMapping: wf.componentMapping || [],
+      layout: wf.layout || null,
+      permissionsRequired: wf.permissionsRequired || []
+    }))
+  },
+  e2eFlows: [],           // Empty — not yet consolidated
+  dependencyGraph: {
+    nodes: (master.modules || []).map(m => ({
+      id: m.code, label: m.code, type: m.featureType || "data-centric"
+    })),
+    edges: (master.dependencyGraph?.edges || []).map(e => ({
+      from: e.from, to: e.to, description: e.description || ""
+    }))
+  }
+};
+```
+
+> **FIELD RENAME WARNING:** feature.json uses `mockupFormat` and `mockup`.
+> The HTML renderer reads `format` and `content`. You MUST rename these fields.
+> Failure to rename = empty mockup display in the browser.
+
+### Step 4: Replace Placeholders in Template
 
 - Serialize the FEATURE_DATA object as JSON (2-space indentation)
-- Replace `{{FEATURE_DATA}}` with the serialized JSON
+- Serialize the EMBEDDED_ARTIFACTS object as JSON (2-space indentation)
+- Replace `{{FEATURE_DATA}}` with the serialized FEATURE_DATA JSON
+- Replace `{{EMBEDDED_ARTIFACTS}}` with the serialized EMBEDDED_ARTIFACTS JSON
 - Replace `{{APPLICATION_NAME}}` → `{application_name}`
 - Replace `{{APPLICATION_ID}}` → `{feature_id}`
 - Replace `{{VERSION}}` → `{version}`
 - Replace `{{CREATED_AT}}` → `{ISO timestamp}`
 
-### Step 4: Write and Confirm
+### Step 5: Write and Confirm
 
 ```
 ✓ Interactive HTML updated (incremental):
   Path: docs/business/{app}/business-analyse/v{version}/ba-interactive.html
   Modules included: {completedModules.length}/{totalModules} specified
-    - {completedModule1}: {uc_count} UCs, {br_count} BRs, {entity_count} entities
+    - {completedModule1}: {uc_count} UCs, {br_count} BRs, {wireframe_count} wireframes
     - {completedModule2}: ...
+  Visual artifacts: {total_wireframes} wireframes embedded
   Remaining: {pendingModules.join(', ')} (will be added after specification)
   → Client can open in browser to review completed modules now.
 ```

package/templates/skills/business-analyse/references/validation-checklist.md

@@ -0,0 +1,281 @@
+# Module Specification Checklist
+
+> **CRITICAL:** This checklist MUST be FULLY COMPLETED before marking module status = "specified".
+> **Rationale:** Prevents incomplete modules from reaching handoff, reduces ralph-loop failures.
+
+## Checklist Structure
+
+**Execute BEFORE updating module status to "specified":**
+
+```javascript
+const checklist = {
+  // SECTION 1: DATA MODEL (BLOCKING)
+  entities: {
+    minimum: 2,
+    actual: specification.entities.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "At least 2 entities required for a meaningful module"
+  },
+
+  entityAttributes: {
+    check: "All entities have ≥3 attributes",
+    status: validateAllEntities(e => e.attributes.length >= 3) ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Entities with <3 attributes are likely incomplete"
+  },
+
+  entityRelationships: {
+    check: "All entities have relationships defined (or explicitly marked as standalone)",
+    status: validateEntityRelationships() ? "PASS" : "FAIL",
+    blocking: false,  // WARNING only
+    details: "Standalone entities should be rare in business modules"
+  },
+
+  // SECTION 2: BUSINESS RULES (BLOCKING)
+  businessRules: {
+    minimum: 4,
+    actual: analysis.businessRules.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum 4 BRs (mix of VAL/CALC/WF/SEC/DATA)"
+  },
+
+  businessRuleCategories: {
+    check: "BRs cover ≥2 categories (VAL, CALC, WF, SEC, DATA)",
+    status: countUniqueCategories(analysis.businessRules) >= 2 ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Single-category modules are likely incomplete"
+  },
+
+  businessRulePrefixes: {
+    check: "All BR IDs use module prefix (e.g., BR-VAL-{PREFIX}-NNN)",
+    status: validateBRPrefixes() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Missing prefixes cause ID collisions in multi-module apps"
+  },
+
+  // SECTION 3: USE CASES & REQUIREMENTS (BLOCKING)
+  useCases: {
+    minimum: 6,
+    actual: specification.useCases.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum 6 UCs (CRUD + 2 business-specific)"
+  },
+
+  useCasePrefixes: {
+    check: "All UC IDs use module prefix (UC-{PREFIX}-NNN)",
+    status: validateUCPrefixes() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Missing prefixes cause ID collisions"
+  },
+
+  functionalRequirements: {
+    minimum: 4,
+    actual: specification.functionalRequirements.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "FRs must cover key functionality"
+  },
+
+  ucFrLinkage: {
+    check: "Every UC has ≥1 linked FR",
+    status: validateUCtoFRLinkage() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Orphan UCs indicate incomplete requirements"
+  },
+
+  frBrLinkage: {
+    check: "Every FR has ≥1 linked BR",
+    status: validateFRtoBRLinkage() ? "PASS" : "FAIL",
+    blocking: false,  // WARNING only
+    details: "FRs without BRs may lack validation/calculation logic"
+  },
+
+  // SECTION 4: PERMISSIONS (BLOCKING)
+  permissions: {
+    minimum: 5,
+    actual: specification.permissionMatrix.permissions.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum 5 permissions (CRUD + 1 business action)"
+  },
+
+  permissionFormat: {
+    check: "All permissions use full format: business.{app}.{module}.{resource}.{action}",
+    status: validatePermissionFormat() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Wrong format breaks RBAC system"
+  },
+
+  rolePermissions: {
+    check: "All application roles have ≥1 permission assigned",
+    status: validateRoleAssignments() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Roles without permissions are useless"
+  },
+
+  // SECTION 5: UI & NAVIGATION (BLOCKING)
+  sections: {
+    minimum: 2,
+    actual: specification.sections.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Modules need ≥2 sections (list + form minimum)"
+  },
+
+  wireframes: {
+    minimum: specification.sections.length,  // 1 wireframe PER section
+    actual: specification.uiWireframes.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "EVERY section MUST have a wireframe (ASCII/SVG)"
+  },
+
+  navigation: {
+    check: "Module has ≥1 navigation entry",
+    status: specification.navigation.entries.length >= 1 ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Module must be accessible in menu"
+  },
+
+  // SECTION 6: I18N & MESSAGES (BLOCKING)
+  i18nKeys: {
+    minimum: 42,  // Realistic minimum for a module
+    actual: specification.i18nKeys.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Keys needed: entities (×2), fields, messages, validation, navigation"
+  },
+
+  i18nLanguages: {
+    check: "All i18n keys have 4 languages (fr, en, nl, de)",
+    status: validateI18nCompleteness() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Missing translations break multi-language support"
+  },
+
+  messages: {
+    minimum: 4,
+    actual: specification.messages.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum: 1 success, 1 error, 1 warning, 1 info"
+  },
+
+  // SECTION 7: SEED DATA (BLOCKING)
+  seedDataCore: {
+    check: "All 7 CORE seed data sections present",
+    requiredSections: [
+      "navigationModules",
+      "navigationSections",
+      "navigationResources",
+      "navigationTranslations",
+      "permissions",
+      "rolePermissions",
+      "permissionConstants"
+    ],
+    status: validateSeedDataCore() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Missing CORE seed data breaks module deployment"
+  },
+
+  seedDataBusiness: {
+    check: "Business seed data template defined for modules with reference/lookup entities",
+    status: specification.seedDataBusiness !== undefined ? "PASS" : "FAIL",
+    blocking: true,  // BLOCKING — missing seed data causes empty dropdowns and test failures
+    details: "Business seed data (reference types, categories, statuses) is required for testing and dev environment"
+  },
+
+  // SECTION 8: API ENDPOINTS (BLOCKING)
+  apiEndpoints: {
+    minimum: 5,
+    actual: specification.apiEndpoints.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Minimum 5 endpoints (CRUD + 1 business action)"
+  },
+
+  apiPermissions: {
+    check: "Every API endpoint has permission defined",
+    status: validateAPIPermissions() ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Endpoints without permissions are security holes"
+  },
+
+  // SECTION 9: VALIDATIONS (BLOCKING)
+  validations: {
+    minimum: 1,
+    actual: specification.validations.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: true,
+    details: "Modules need field validation rules"
+  },
+
+  // SECTION 10: GHERKIN SCENARIOS (WARNING)
+  gherkinScenarios: {
+    minimum: 2,
+    actual: specification.gherkinScenarios.scenarios.length,
+    status: actual >= minimum ? "PASS" : "FAIL",
+    blocking: false,  // WARNING only
+    details: "Gherkin scenarios enable automated testing"
+  }
+};
+```
+
+## Blocking Check Logic
+
+```javascript
+// BLOCKING CHECK: Count failures in BLOCKING items
+const blockingFailures = Object.entries(checklist)
+  .filter(([key, check]) => check.blocking === true && check.status === "FAIL")
+  .map(([key, check]) => ({ section: key, ...check }));
+
+IF blockingFailures.length > 0:
+  **BLOCKING ERROR:** Module specification incomplete
+
+  Display table:
+  | Section | Required | Actual | Status | Details |
+  |---------|----------|--------|--------|---------|
+  {for each blocking failure}
+
+  ACTIONS REQUIRED:
+  1. Fix ALL blocking failures listed above
+  2. Re-run step-03d validation
+  3. DO NOT mark module as "specified" until ALL blocking checks pass
+
+  STOP - DO NOT PROCEED TO UPDATE STATUS
+ELSE:
+  All blocking checks passed ✓
+  {count} warnings (non-blocking)
+  Proceed to mark module as "specified"
+```
+
+## Display Format
+
+```
+═══════════════════════════════════════════════════════════════
+  MODULE SPECIFICATION CHECKLIST - {currentModule}
+═══════════════════════════════════════════════════════════════
+
+| Category | Checks | Passed | Failed | Warnings |
+|----------|--------|--------|--------|----------|
+| Data Model | 3 | {n} | {n} | {n} |
+| Business Rules | 3 | {n} | {n} | {n} |
+| Use Cases & FRs | 4 | {n} | {n} | {n} |
+| Permissions | 3 | {n} | {n} | {n} |
+| UI & Navigation | 3 | {n} | {n} | {n} |
+| I18N & Messages | 3 | {n} | {n} | {n} |
+| Seed Data | 2 | {n} | {n} | {n} |
+| API Endpoints | 2 | {n} | {n} | {n} |
+| Validations | 1 | {n} | {n} | {n} |
+| Gherkin | 1 | {n} | {n} | {n} |
+
+TOTAL: {total_checks} checks | {passed} ✓ | {failed} ✗ | {warnings} ⚠
+
+STATUS: {failed === 0 ? "READY FOR SPECIFIED" : "INCOMPLETE - FIX REQUIRED"}
+═══════════════════════════════════════════════════════════════
+```
+
+**IF ALL BLOCKING CHECKS PASS → Proceed to update module status to "specified"**

package/templates/skills/business-analyse/steps/step-00-init.md

@@ -69,94 +69,51 @@ mcp__smartstack__validate_conventions({ checks: ["tables"] })
 **DO NOT** continue to any subsequent step.
 **STOP the skill immediately.**
 
-## Step 2a: Check for Review Mode
-
-If `{feature_description}` starts with `-review` (with or without extra text):
-
-1. Set `workflow_type = "review"`
-2. Scan `docs/business/` for the most recent application (by updatedAt)
-3. For the latest application version folder, look for `ba-review.json`
-4. If found:
-   - Store `review_json_path` = path to `ba-review.json`
-   - Store `application_name` from the master feature.json metadata
-   - Store `docs_dir` = directory containing `ba-review.json`
-   - Display:
-     ```
-     Review mode: found ba-review.json at {review_json_path}
-     Application: {application_name}
-     ```
-   - **SKIP all remaining steps** → Load `./step-06-review.md` directly
-5. If NOT found:
-   - Display error:
-     ```
-     ERROR: No ba-review.json found in docs/business/
-
-     To create one:
-     1. Open the ba-interactive.html in your browser
-     2. Make your corrections
-     3. Click "Sauvegarder corrections" button
-     4. Save the downloaded ba-review.json in the version folder
-        (e.g., docs/business/{app}/business-analyse/v1.0/ba-review.json)
-     5. Run /business-analyse -review again
-     ```
-   - **STOP EXECUTION**
-
-## Step 2b: Scan Existing Applications
-
-Scan `docs/business/` for existing business analysis features.
+## Step 2-3: Workflow Detection (Review / New / Update)
 
-```
-1. Glob: docs/business/*/business-analyse/*/feature.json
-2. For each feature.json found:
-   - Read metadata.application, metadata.featureDescription
-   - Store: { app: string, featureId: string, description: string, version: string }
-3. Build list of existing applications
-```
+**Objective:** Detect workflow type and match against existing applications.
 
-**Store:**
-```yaml
-existing_apps: array of { app, featureId, description, version }
-```
+**Process:**
 
-## Step 3: Auto-Detect New vs Update (skipped in review mode)
+Execute workflow detection algorithm:
+1. **Review Mode Detection:** Check if `{feature_description}` starts with `-review`
+2. **Existing Applications Scanner:** Glob `docs/business/*/business-analyse/*/feature.json`
+3. **Similarity Analysis:** Score user intent against existing apps (>= 80 = strong match)
+4. **Decision Tree:** Prompt user with relevant options
 
-Compare the user's `{feature_description}` with existing applications.
+```javascript
+const detectionResult = detectWorkflowType(feature_description, existingApps);
 
-```
-IF existing_apps is empty:
-  workflow_type = "new"
-  → Go to Step 4
+IF detectionResult.error OR detectionResult.ambiguous:
+  // CONDITIONAL LOAD: Only load detection strategies on error or ambiguity
+  Read references/detection-strategies.md
+  Display:
+    - Detailed similarity scoring algorithm
+    - Decision tree with thresholds
+    - Error handling procedures
+    - Review mode troubleshooting (if review mode failed)
 
-IF existing_apps has entries:
-  Analyze {feature_description} for similarity with existing apps:
-    - Same application domain?
-    - References an existing module name?
-    - Mentions adding/changing/modifying something existing?
+  → Resolve ambiguity with user clarification
 
-  Ask via AskUserQuestion:
-    question: "J'ai trouvé des analyses existantes. Que souhaitez-vous faire ?"
-    header: "Mode"
-    options:
-      - label: "Nouvelle application"
-        description: "Créer une nouvelle analyse complète"
-      - label: "Mise à jour de {appName} (FEAT-NNN)"
-        description: "Enrichir ou modifier l'application existante (crée v{next})"
-    (repeat for each existing app, max 3 options + "Nouvelle application")
-
-  IF user selects "Nouvelle application":
-    workflow_type = "new"
-  ELSE:
-    workflow_type = "update"
-    existing_feature_id = selected app's featureId
-    Call ba-writer.createVersion(existing_feature_id, {feature_description})
-    version = new version number
+ELSE:
+  Workflow detected: {detectionResult.workflow_type} ✓
+  → Continue to application name determination
 ```
 
+**Key decision points:**
+1. IF review mode → load ba-review.json, skip to step-06-review.md
+2. IF no existing apps → workflow_type = "new"
+3. IF existing apps → analyze similarity → prompt user
+
+**Optimization:** The detailed 400-line detection-strategies.md is loaded **only when detection fails or is ambiguous** (saves ~15,000 tokens on clear detection path).
+
 **Store:**
 ```yaml
-workflow_type: "new" | "update"
+workflow_type: "new" | "update" | "review"
 existing_feature_id: string | null
 version: "1.0" (new) | "1.1"+ (update)
+review_json_path: string | null (review only)
+existing_apps: array of { app, featureId, description, version }
 ```
 
 ## Step 4: Determine Application Name
@@ -279,169 +236,41 @@ See [references/init-schema-deployment.md](../references/init-schema-deployment.
 
 ## Step 8b: Cache Warming (PERFORMANCE OPTIMIZATION)
 
-> **Objective:** Pre-load frequently-used templates and context files to reduce redundant reads in subsequent steps.
-> **Expected token savings:** 15-20% across the entire BA session
-
-**Why cache warming matters:**
+> **Objective:** Pre-load frequently-used templates and context files to reduce redundant reads.
+> **Expected token savings:** 15-20% across entire BA session
 
-Analysis of BA sessions shows 98.5% cache read operations, meaning the same files are re-read multiple times. By pre-loading them once at initialization, we reduce:
-- Redundant file reads (5+ reads of same schema files)
-- Token waste on repeated context setup
-- Agent execution time (no wait for file I/O)
-
-### Cache Buckets Strategy
-
-Organize cached content into logical buckets based on when they'll be used:
+**Implementation:**
 
 ```javascript
-const cacheBuckets = {
-  // Bucket 1: Core schemas (used in ALL steps)
-  schemas: {
-    retention: "session",  // Keep for entire BA session
-    files: [
-      "docs/business/{app}/business-analyse/schemas/feature-schema.json",
-      "docs/business/{app}/business-analyse/schemas/application-schema.json",
-      "docs/business/{app}/business-analyse/schemas/sections/*.json",
-      "docs/business/{app}/business-analyse/schemas/shared/common-defs.json"
-    ],
-    priority: "critical"
-  },
-
-  // Bucket 2: Questionnaire templates (used in step-01)
-  questionnaires: {
-    retention: "until-step-02",  // Can clear after cadrage
-    files: [
-      "~/.claude/skills/business-analyse/questionnaire/*.md",
-      "~/.claude/skills/business-analyse/patterns/suggestion-catalog.md"
-    ],
-    priority: "high"
-  },
-
-  // Bucket 3: Module specification references (used in step-03)
-  moduleSpec: {
-    retention: "until-step-04",  // Can clear after all modules specified
-    files: [
-      "~/.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"
-    ],
-    priority: "medium"
-  },
-
-  // Bucket 4: Handoff & deploy templates (used in step-05)
-  handoff: {
-    retention: "until-complete",
-    files: [
-      "~/.claude/skills/business-analyse/references/handoff-file-templates.md",
-      "~/.claude/skills/business-analyse/references/handoff-mappings.md",
-      "~/.claude/skills/business-analyse/references/deploy-data-build.md",
-      "~/.claude/skills/business-analyse/html/ba-interactive.html"
-    ],
-    priority: "low"  // Load later, not at init
-  }
-};
-```
-
-### Implementation at Step 8b
-
-**ONLY pre-load CRITICAL and HIGH priority buckets at initialization:**
-
-```javascript
-// 1. Pre-load schemas (Bucket 1 - CRITICAL)
+// Pre-load CRITICAL (schemas) and HIGH (questionnaires) priority buckets
 const schemaFiles = glob("docs/business/{app}/business-analyse/schemas/**/*.json");
 for (const file of schemaFiles) {
-  const content = read(file);
-  // Content is now in cache for subsequent reads
-  // No need to store in variable, just reading triggers cache
+  read(file);  // Triggers cache
 }
 
-// 2. Pre-load questionnaires (Bucket 2 - HIGH, if step-01 is next)
 const questionnaireFiles = glob("~/.claude/skills/business-analyse/questionnaire/*.md");
 for (const file of questionnaireFiles) {
-  const content = read(file);
+  read(file);  // Triggers cache
 }
 
-// 3. Pre-load suggestion catalog
-const suggestions = read("~/.claude/skills/business-analyse/patterns/suggestion-catalog.md");
+read("~/.claude/skills/business-analyse/patterns/suggestion-catalog.md");
 
-// 4. Display cache warming status
+// Display status
 console.log(`
-✓ Cache warmed: 9 schemas + 16 questionnaires + 1 suggestion catalog
-  Expected token savings: 15-20% over session
-  Cache retention: schemas (session-wide), questionnaires (until step-02)
+✓ Cache warmed: 9 schemas + 16 questionnaires + 1 catalog
+  Expected savings: 15-20% session tokens
+  Retention: schemas (session-wide), questionnaires (until step-02)
 `);
 ```
 
-### Cache Retention Rules
-
-| Bucket | Load At | Clear At | Reason |
-|--------|---------|----------|--------|
-| schemas | step-00 | session end | Used by ALL steps for validation |
-| questionnaires | step-00 | step-02 | Only needed for cadrage |
-| moduleSpec | step-03 start | step-04 | Only needed for module loop |
-| handoff | step-05a start | session end | Only needed for handoff/deploy |
-
-### Benefits
-
-**Measured impact (from analysis):**
-
-- **Before warming:**
-  - Schema files read 5-7 times per session
-  - Questionnaires read 2-3 times
-  - Total redundant reads: ~30 file operations
-  - Token cost: ~15,000 tokens wasted
-
-- **After warming:**
-  - Schema files read once (cached for session)
-  - Questionnaires read once (cached until step-02)
-  - Total redundant reads: ~5 file operations (90% reduction)
-  - Token cost: ~3,000 tokens (80% reduction)
-
-**Overall session impact:** 15-20% total token savings
-
-### When NOT to Pre-Load
-
-❌ **Don't pre-load:**
-- Files that will NOT be used (e.g., handoff templates during cadrage)
-- Large files (>50KB) that are read only once
-- Module-specific feature.json files (loaded on-demand)
-- User-generated content (changes frequently)
-
-✅ **DO pre-load:**
-- Small, static template files (<10KB) used 3+ times
-- Core schemas used in every step
-- Questionnaire templates used in next step
-- Pattern catalogs referenced frequently
-
-### Monitoring Cache Efficiency
-
-After cache warming, monitor cache hit rates:
-
-```
-Step-01 cache stats:
-  - schema-read operations: 12 (100% cache hits)
-  - questionnaire-read operations: 16 (100% cache hits)
-  - Cache efficiency: Optimal (0 redundant reads)
-```
-
-Compare to baseline (no warming):
-```
-Step-01 cache stats (baseline):
-  - schema-read operations: 12 (8 cache hits, 4 misses = 67% efficiency)
-  - questionnaire-read operations: 16 (5 cache hits, 11 misses = 31% efficiency)
-  - Cache efficiency: Poor (15 redundant reads)
-```
-
-**Success metric:** Cache hit rate > 90% for pre-loaded files
-
-### Reference Documentation
+**Bucket Strategy:**
 
-See [references/cache-warming-strategy.md](../references/cache-warming-strategy.md) for:
-- Complete cache bucket definitions
-- Retention policy details
-- Token savings calculations
-- Cache invalidation rules
-- Advanced: progressive cache warming across steps
+See [references/cache-warming-strategy.md](../references/cache-warming-strategy.md) for complete documentation on:
+- 5 cache buckets (schemas, questionnaires, moduleSpec, handoff, etc.)
+- Retention policies and clearing rules
+- Token savings calculations (baseline vs optimized)
+- Monitoring cache efficiency
+- When to pre-load vs lazy-load
 
 ## Step 9: Create Master feature.json