bmad-module-skill-forge 0.2.0

package/src/workflows/analyze-source/steps-c/step-04-map-and-detect.md

@@ -0,0 +1,222 @@
+---
+name: 'step-04-map-and-detect'
+description: 'Map exports per unit and detect cross-unit integration points, flag stack skill candidates'
+
+nextStepFile: './step-05-recommend.md'
+outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+heuristicsFile: '../data/unit-detection-heuristics.md'
+---
+
+# Step 4: Map Exports and Detect Integrations
+
+## STEP GOAL:
+
+To analyze each qualifying unit's export surface and import graph, detect cross-unit integration points, and flag potential stack skill candidates — completing the analysis foundation needed for recommendations.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+
+### Role Reinforcement:
+
+- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Prescriptive precision — zero-hallucination, only report what is found
+- ✅ File:line citation tracing — cite specific files and line numbers for all claims
+
+### Step-Specific Rules:
+
+- 🎯 Use subprocess optimization (Pattern 2) — per-unit analysis for export mapping
+- 💬 DO NOT BE LAZY — For EACH qualifying unit, perform thorough export surface analysis
+- 🚫 FORBIDDEN to make recommendations in this step (that's step 05)
+- 📋 Tier-aware depth: Quick (file-level exports), Forge (AST export analysis), Deep (AST + semantic relationships)
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Append "## Export Map" and "## Integration Points" sections to {outputFile}
+- 📖 Update stepsCompleted in {outputFile} frontmatter
+- 🚫 FORBIDDEN to proceed without presenting findings to user
+
+## CONTEXT BOUNDARIES:
+
+- Available: Identified Units section from report (qualifying units with paths, types, scope types, languages)
+- Focus: Export surfaces, import graphs, and cross-unit integration patterns
+- Limits: Do not recommend or filter units — present all findings objectively
+- Dependencies: step-03-identify-units must have populated the Identified Units section
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Context
+
+Read {outputFile} to obtain:
+- Qualifying units from Identified Units section (names, paths, scope types, languages)
+- `forge_tier` from frontmatter
+
+Load {heuristicsFile} for stack skill candidate detection rules.
+
+### 2. Map Export Surfaces Per Unit
+
+DO NOT BE LAZY — For EACH qualifying unit, launch a subprocess (or analyze in main thread) that:
+
+1. Scans the unit's directory for export/public interface files
+2. Counts and categorizes exports based on forge tier:
+   - **Quick tier:** Count files by type, identify index/barrel files, list directory structure
+   - **Forge tier:** Parse export statements, identify public API surface, count exported functions/classes/types
+   - **Deep tier:** All Forge analysis plus semantic relationship mapping between exports
+3. Returns structured findings to parent:
+   - Export count (files, functions, types, classes)
+   - Primary export patterns (barrel exports, direct exports, re-exports)
+   - Public API surface size estimate
+   - Key entry points
+
+**Per-unit export summary:**
+
+| Unit | Files | Exports | Export Pattern | API Surface |
+|------|-------|---------|----------------|-------------|
+| {name} | {count} | {count} | {pattern} | {small/medium/large} |
+
+### 3. Map Import Graph
+
+For each qualifying unit, analyze inbound and outbound imports:
+
+**Outbound imports (this unit imports from):**
+- Which other qualifying units does it depend on?
+- Which external dependencies does it use?
+
+**Inbound imports (other units import from this):**
+- Which other qualifying units consume this unit's exports?
+- How many import sites exist?
+
+**Build cross-reference matrix:**
+
+| Unit | Imports From | Imported By | External Deps |
+|------|-------------|-------------|---------------|
+| {name} | {list units} | {list units} | {count} |
+
+### 4. Detect Integration Points
+
+Identify cross-unit integration patterns:
+
+**Direct integrations:**
+- Unit A imports from Unit B → document the interface boundary
+- Shared type definitions across units
+- Cross-unit function calls
+
+**For each integration point document:**
+- Source unit → Target unit
+- Integration type (import, shared types, API call, message passing, shared state)
+- Files involved (with paths)
+- Coupling strength (tight / loose / indirect)
+
+### 5. Flag Stack Skill Candidates
+
+Using rules from {heuristicsFile}, check for stack skill indicators:
+
+1. **Co-import frequency:** Two or more units imported together in 3+ files
+2. **Integration adapter:** A unit exists primarily to bridge two other units
+3. **Shared state:** Multiple units read/write to the same data store
+4. **Orchestration layer:** A unit coordinates calls across multiple other units
+
+**For each candidate, document:**
+- Units involved
+- Detection signal
+- Recommended stack skill grouping
+- Evidence (specific files/lines)
+
+### 6. Present Findings
+
+"**Export Mapping and Integration Detection Complete**
+
+**Export Map Summary:**
+{Per-unit export summary table}
+
+**Cross-Reference Matrix:**
+{Import graph matrix}
+
+**Integration Points:** {count}
+{List each integration with source → target, type, coupling}
+
+**Stack Skill Candidates:** {count}
+{List each candidate with units involved and detection signal}
+
+**Observations:**
+- {Key architectural patterns observed}
+- {Tightly coupled areas}
+- {Loosely coupled areas ideal for independent skills}
+
+Does this analysis look complete? Any integration patterns I should investigate further?"
+
+Wait for user feedback. Adjust analysis based on user input.
+
+### 7. Append to Report
+
+Append the complete "## Export Map" section to {outputFile}:
+Replace `[Appended by step-04-map-and-detect]` under Export Map with:
+- Per-unit export summary table
+- Export pattern analysis
+
+Append the complete "## Integration Points" section to {outputFile}:
+Replace `[Appended by step-04-map-and-detect]` under Integration Points with:
+- Cross-reference matrix
+- Integration point details
+- Stack skill candidate flags
+
+Update {outputFile} frontmatter:
+```yaml
+stepsCompleted: ['step-01-init', 'step-02-scan-project', 'step-03-identify-units', 'step-04-map-and-detect']
+lastStep: 'step-04-map-and-detect'
+stack_skill_candidates: [{list flagged candidate groupings}]
+```
+
+### 8. Present MENU OPTIONS
+
+Display: "**Select:** [C] Continue to Recommendations"
+
+#### Menu Handling Logic:
+
+- IF C: Save findings to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF Any other: help user, then [Redisplay Menu Options](#8-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN both the Export Map and Integration Points sections have been appended to {outputFile} with complete findings, and frontmatter stepsCompleted and stack_skill_candidates have been updated, will you load and read fully {nextStepFile} to begin recommendations.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Every qualifying unit's export surface mapped with tier-appropriate depth
+- Import graph built showing cross-unit dependencies
+- Integration points documented with coupling strength
+- Stack skill candidates flagged with evidence
+- Findings presented to user for confirmation
+- Report updated with both Export Map and Integration Points sections
+- stepsCompleted and stack_skill_candidates updated in frontmatter
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping units during export analysis (DO NOT BE LAZY)
+- Not building the cross-reference matrix
+- Missing stack skill candidate detection
+- Making recommendations in this step (that's step 05)
+- Not citing specific files for integration points
+- Not presenting findings for user confirmation
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/analyze-source/steps-c/step-05-recommend.md

@@ -0,0 +1,236 @@
+---
+name: 'step-05-recommend'
+description: 'Present unit recommendations with rationale for user confirmation or rejection'
+
+nextStepFile: './step-06-generate-briefs.md'
+outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+schemaFile: '../data/skill-brief-schema.md'
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Step 5: Recommend
+
+## STEP GOAL:
+
+To present each qualifying unit as a recommendation with evidence-based rationale, allow the user to confirm, reject, or modify each recommendation, and build the confirmed units list that drives brief generation.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+
+### Role Reinforcement:
+
+- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Prescriptive precision — zero-hallucination, every recommendation backed by evidence
+- ✅ This is the COLLABORATIVE GATE — user must explicitly confirm each unit
+
+### Step-Specific Rules:
+
+- 🎯 This is the primary user decision point — do NOT rush through it
+- 🚫 FORBIDDEN to proceed without explicit confirmation for each unit
+- 💬 Present evidence for each recommendation, invite questions and pushback
+- 📋 User can ask "why?" for any recommendation — explain with specific file citations
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Append "## Recommendations" section to {outputFile}
+- 📖 Update stepsCompleted and confirmed_units in {outputFile} frontmatter
+- 🚫 FORBIDDEN to generate briefs in this step (that's step 06)
+
+## CONTEXT BOUNDARIES:
+
+- Available: Full report — Project Scan, Identified Units, Export Map, Integration Points
+- Focus: Presenting evidence-based recommendations and capturing user decisions
+- Limits: Do not generate skill-brief.yaml files — only confirm which units to brief
+- Dependencies: steps 02-04 must have populated scan, units, exports, and integrations
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Context
+
+Read {outputFile} completely to obtain:
+- Qualifying units from Identified Units
+- Export map data per unit
+- Integration points and coupling analysis
+- Stack skill candidates from frontmatter
+- Existing skills from frontmatter
+
+Load {schemaFile} for reference on what skill-brief.yaml requires (so recommendations are actionable).
+
+### 2. Build Recommendation Cards
+
+For EACH qualifying unit, prepare a recommendation card:
+
+```
+**Unit: {name}**
+- Path: {path}
+- Language: {language}
+- Boundary: {type} | Scope: {scope_type}
+- Exports: {count} ({pattern})
+- API Surface: {size}
+- Integrations: imports from {list}, imported by {list}
+- Coupling: {tight/loose/indirect}
+- Confidence: {high/medium/low}
+- Stack Skill: {yes — grouped with {units} / no}
+- Status: {new / already-skilled → recommend update-skill}
+
+**Rationale:** {2-3 sentences explaining WHY this should be a skill, citing specific detection signals and file paths}
+
+**Proposed Brief Fields:**
+- name: {suggested kebab-case name}
+- scope.type: {full-library / specific-modules / public-api}
+- scope.include: {suggested glob patterns}
+- description: {suggested 1-3 sentence description}
+```
+
+### 3. Present Recommendations
+
+"**Recommendations for {project_name}**
+
+I've analyzed {count} qualifying units. Here are my recommendations for skill creation:
+
+---"
+
+Present each recommendation card, then after ALL cards:
+
+"---
+
+**Summary:**
+- **Recommended for new skills:** {count}
+- **Already-skilled (recommend update-skill):** {count}
+- **Stack skill candidates:** {count}
+
+**For each unit above, please indicate:**
+- **Y** — Confirm: generate skill-brief.yaml
+- **N** — Reject: skip this unit
+- **M** — Modify: adjust name, scope, or description before confirming
+
+You can respond with a list (e.g., '1:Y, 2:Y, 3:N, 4:M') or address each individually.
+
+**Questions?** Ask 'why?' about any recommendation and I'll explain my reasoning with specific evidence."
+
+### 4. Process User Decisions
+
+For each unit:
+
+**IF Y (Confirm):**
+- Add to confirmed_units list with proposed brief fields
+
+**IF N (Reject):**
+- Document rejection with user's reason (if provided)
+- Remove from confirmed list
+
+**IF M (Modify):**
+- Ask what to modify (name, scope, description, scope.include patterns)
+- Update the recommendation with user changes
+- Confirm the modified version
+
+**Continue until ALL units have a decision (Y/N/M).**
+
+### 5. Confirm Stack Skill Candidates
+
+If stack skill candidates were flagged:
+
+"**Stack Skill Candidates:**
+
+The following unit groupings show strong co-integration patterns and may benefit from a consolidated stack skill via create-stack-skill:
+
+{For each candidate: list units, detection signal, evidence}
+
+Would you like to flag these for create-stack-skill? (Y/N per candidate)"
+
+Document decisions.
+
+### 6. Present Final Confirmation
+
+"**Confirmed Units for Brief Generation:** {count}
+
+{List each confirmed unit with final name, scope type, and description}
+
+**Rejected Units:** {count}
+{List with reasons}
+
+**Stack Skill Flags:** {count}
+{List groupings flagged for create-stack-skill}
+
+**This is your final confirmation before I generate skill-brief.yaml files.** All confirmed?"
+
+Wait for explicit final confirmation.
+
+### 7. Append to Report
+
+Append the complete "## Recommendations" section to {outputFile}:
+
+Replace `[Appended by step-05-recommend]` with:
+- All recommendation cards (including rationale)
+- User decisions per unit (confirmed/rejected/modified)
+- Stack skill candidate decisions
+- Final confirmation status
+
+Update {outputFile} frontmatter:
+```yaml
+stepsCompleted: ['step-01-init', 'step-02-scan-project', 'step-03-identify-units', 'step-04-map-and-detect', 'step-05-recommend']
+lastStep: 'step-05-recommend'
+confirmed_units: [{list of confirmed unit names}]
+stack_skill_candidates: [{updated list with user decisions}]
+```
+
+### 8. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Brief Generation"
+
+#### Menu Handling Logic:
+
+- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
+- IF C: Save recommendations to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions — always respond and then redisplay menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN all units have explicit user decisions (Y/N/M), the confirmed_units list is finalized in frontmatter, and the user has given final confirmation, will you load and read fully {nextStepFile} to begin brief generation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Every qualifying unit presented with evidence-based recommendation
+- User explicitly decided on each unit (Y/N/M)
+- Modifications captured and confirmed
+- Stack skill candidates addressed
+- Already-skilled units directed to update-skill
+- Final confirmation obtained before proceeding
+- Report updated with complete Recommendations section
+- confirmed_units populated in frontmatter
+
+### ❌ SYSTEM FAILURE:
+
+- Auto-confirming units without user decision
+- Not presenting evidence/rationale for recommendations
+- Skipping the final confirmation
+- Generating skill-brief.yaml files in this step (that's step 06)
+- Not documenting rejection reasons
+- Proceeding with empty confirmed_units list without user acknowledgment
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/analyze-source/steps-c/step-06-generate-briefs.md

@@ -0,0 +1,239 @@
+---
+name: 'step-06-generate-briefs'
+description: 'Generate skill-brief.yaml per confirmed unit, write analysis summary, recommend next workflow'
+
+outputFile: '{output_folder}/analyze-source-report-{project_name}.md'
+schemaFile: '../data/skill-brief-schema.md'
+---
+
+# Step 6: Generate Briefs
+
+## STEP GOAL:
+
+To generate a valid skill-brief.yaml file for each confirmed unit using the schema, write the files to the forge data folder, append generation results to the analysis report, and recommend the appropriate next workflow for each unit — completing the analyze-source workflow.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+
+### Role Reinforcement:
+
+- ✅ You are a source code analyst and decomposition architect (Ferris Architect mode)
+- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
+- ✅ Prescriptive precision — zero-hallucination, every brief field backed by evidence from prior steps
+- ✅ This is the GENERATION step — produce files that are immediately consumable by downstream workflows
+
+### Step-Specific Rules:
+
+- 🎯 Generate ONLY for units in confirmed_units — no extras, no omissions
+- 🚫 FORBIDDEN to modify recommendations or re-ask for confirmations (that was step 05)
+- 💬 Every generated field must trace back to data collected in steps 02-05
+- 📋 Validate each brief against the schema before writing
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Write skill-brief.yaml files to `{forge_data_folder}/{unit-name}/`
+- 💾 Append "## Generation Results" section to {outputFile}
+- 📖 Update stepsCompleted and mark workflow COMPLETE in {outputFile} frontmatter
+- 🚫 FORBIDDEN to skip validation of generated briefs
+
+## CONTEXT BOUNDARIES:
+
+- Available: Full report — all sections from steps 02-05, confirmed_units list, stack_skill_candidates
+- Focus: YAML generation, file writing, downstream workflow recommendation
+- Limits: Do not re-analyze source code — use only data already captured in the report
+- Dependencies: step-05-recommend must have populated confirmed_units with at least one entry
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Context
+
+Read {outputFile} completely to obtain:
+- `confirmed_units` from frontmatter (names of units approved in step 05)
+- `project_path`, `forge_tier`, `user_name`, `forge_data_folder` from frontmatter
+- Recommendation cards from "## Recommendations" section (proposed brief fields per unit)
+- Export map and integration data from prior sections
+
+Load {schemaFile} for validation reference.
+
+**Guard clause:** If `confirmed_units` is empty, present:
+"**No confirmed units to generate briefs for.** The analysis is complete with no skill briefs produced. Run analyze-source again with different scope or parameters if needed."
+Mark workflow complete and halt.
+
+### 2. Generate Skill-Brief YAML Per Unit
+
+For EACH unit in `confirmed_units`, construct a skill-brief.yaml using:
+
+**Field mapping:**
+
+| Field | Source |
+|-------|--------|
+| name | Confirmed name from step 05 recommendation card |
+| version | `1.0.0` (default for new briefs) |
+| source_repo | `{project_path}` from frontmatter |
+| language | Primary language detected in step 03 |
+| scope.type | Scope type from step 05 recommendation card |
+| scope.include | Include patterns from step 05 recommendation card |
+| scope.exclude | Inferred from heuristics (test files, generated code) |
+| scope.notes | Rationale from step 05 recommendation card |
+| description | Description from step 05 recommendation card |
+| forge_tier | `{forge_tier}` from frontmatter |
+| created | Current date (ISO format YYYY-MM-DD) |
+| created_by | `{user_name}` from frontmatter |
+
+### 3. Validate Each Brief
+
+For each generated brief, check against {schemaFile} validation rules:
+
+1. **Name uniqueness** — no duplicate names within the batch or existing skills
+2. **Source accessible** — project_path exists
+3. **Language recognized** — valid programming language identifier
+4. **Scope type valid** — matches `full-library`, `specific-modules`, or `public-api`
+5. **Include patterns** — at least one glob pattern present
+6. **Forge tier match** — matches forge_tier from config
+
+**If validation fails for any brief:**
+- Document the failure with specific field and reason
+- Present to user for correction before writing
+- Do NOT write invalid briefs
+
+### 4. Present Generation Preview
+
+"**Skill Brief Generation Preview**
+
+**Units to generate:** {count}
+
+{For each unit:}
+---
+**{unit-name}** → `{forge_data_folder}/{unit-name}/skill-brief.yaml`
+```yaml
+{complete YAML content}
+```
+---
+
+**Validation:** {all passed / N issues found}
+{List any validation issues}
+
+**Ready to write {count} skill-brief.yaml files.** Confirm to proceed? (Y to write / N to abort / M to modify a specific brief)"
+
+Wait for explicit user confirmation before writing files.
+
+### 5. Write Files
+
+**IF user confirms (Y):**
+
+For each confirmed brief:
+1. Create directory `{forge_data_folder}/{unit-name}/` if it does not exist
+2. Write `skill-brief.yaml` to `{forge_data_folder}/{unit-name}/skill-brief.yaml`
+3. Verify file was written successfully
+
+**IF user modifies (M):**
+- Ask which brief and what to change
+- Update the YAML, re-validate, present again
+- Return to confirmation prompt
+
+**IF user aborts (N):**
+- Document abort decision
+- Skip file writing, proceed to report update
+
+### 6. Determine Next Workflow Per Unit
+
+For each generated brief, recommend the appropriate next workflow:
+
+| Condition | Recommendation |
+|-----------|---------------|
+| Brief has `scope.type: full-library` and unit is well-bounded | create-skill — brief is sufficient for direct skill creation |
+| Brief has `scope.type: specific-modules` or scope needs refinement | brief-skill — refine scope before creating skill |
+| Brief has `scope.type: public-api` or complex interface | brief-skill — detailed scoping needed |
+| Unit flagged as stack skill candidate | create-stack-skill — after individual skills exist |
+| Unit flagged as already-skilled | update-skill — refresh existing skill |
+
+### 7. Append to Report
+
+Append the complete "## Generation Results" section to {outputFile}:
+
+Replace `[Appended by step-06-generate-briefs]` with:
+
+**Generated Briefs:**
+| # | Unit Name | Output Path | Validation | Next Workflow |
+|---|-----------|-------------|------------|---------------|
+| {n} | {name} | {path} | {pass/fail} | {recommendation} |
+
+**Generation Summary:**
+- Total confirmed units: {count}
+- Briefs generated: {count}
+- Briefs skipped/failed: {count}
+- Stack skill candidates flagged: {count}
+
+**Next Steps:**
+{For each next workflow recommendation, a clear action item}
+
+Update {outputFile} frontmatter:
+```yaml
+stepsCompleted: ['step-01-init', 'step-02-scan-project', 'step-03-identify-units', 'step-04-map-and-detect', 'step-05-recommend', 'step-06-generate-briefs']
+lastStep: 'step-06-generate-briefs'
+nextWorkflow: '{primary recommendation}'
+```
+
+### 8. Present Completion Summary
+
+"**Analyze-Source Workflow Complete**
+
+**Project:** {project_name}
+**Forge Tier:** {forge_tier}
+
+**Results:**
+- **Scanned:** {boundary count} boundaries detected
+- **Identified:** {unit count} qualifying units classified
+- **Confirmed:** {confirmed count} units approved for brief generation
+- **Generated:** {brief count} skill-brief.yaml files written
+
+**Files Created:**
+{List each skill-brief.yaml with full path}
+
+**Analysis Report:** {outputFile}
+
+**Recommended Next Steps:**
+{For each unit, the recommended next workflow with brief explanation}
+
+{If stack skill candidates exist:}
+**Stack Skill Candidates:**
+{List candidates with recommendation to run create-stack-skill after individual skills are created}
+
+**This analysis is complete.** To refine any brief, run the recommended next workflow. To re-analyze with different scope, run analyze-source again."
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Every confirmed unit has a skill-brief.yaml generated and validated
+- All 9 required schema fields present and valid in each brief
+- Files written to correct paths in forge_data_folder
+- User confirmed before files were written
+- Next workflow recommended per unit
+- Generation Results section appended to report
+- stepsCompleted fully populated and workflow marked complete
+- Completion summary presented with clear next steps
+
+### ❌ SYSTEM FAILURE:
+
+- Generating briefs for units NOT in confirmed_units
+- Writing files without user confirmation
+- Missing required schema fields in generated YAML
+- Not validating briefs against schema before writing
+- Re-analyzing source code instead of using report data
+- Not recommending next workflow per unit
+- Not marking workflow as complete in frontmatter
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.