bmad-module-skill-forge 0.6.0 → 0.7.1

package/src/workflows/refine-architecture/data/refinement-rules.md

@@ -0,0 +1,102 @@
+# Architecture Refinement Rules
+
+## Purpose
+
+Rules for detecting gaps, issues, and improvements in an architecture document using generated skill data as the evidence source.
+
+---
+
+## Gap Detection Rules
+
+Gaps are undocumented integration paths — library pairs that have compatible APIs but no architecture description.
+
+### Detection Method
+
+1. Generate all possible library pairs from the skill inventory
+2. For each pair, check if both skills export APIs that could connect (compatible types, shared protocols, complementary producer/consumer patterns)
+3. Cross-reference against the architecture document: does the document describe how these two libraries interact?
+4. If compatible APIs exist but NO architecture description exists, this is a **gap**
+
+### Gap Classification
+
+| Gap Type | Description | Example |
+|----------|-------------|---------|
+| **Missing Integration Path** | Two libraries can connect but the architecture never describes how | Skill A exports JSON producer, Skill B accepts JSON input, no mention of A-to-B flow |
+| **Undocumented Data Flow** | Data moves between libraries but the flow is not described | Architecture mentions both libraries but not their data exchange mechanism |
+| **Absent Bridge Layer** | Cross-language or cross-protocol libraries need a bridge not mentioned | Rust library and TypeScript library with no IPC/FFI description |
+
+---
+
+## Issue Detection Rules
+
+Issues are contradictions between architecture claims and verified API reality from the skills.
+
+### Detection Method
+
+1. Extract every integration claim from the architecture document (prose co-mention analysis)
+2. For each claim, verify against the actual API surfaces in the skills
+3. Flag contradictions: claimed APIs that do not exist, assumed compatibility that breaks, missing bridge layers
+
+### Issue Classification
+
+| Issue Type | Description | Example |
+|------------|-------------|---------|
+| **API Mismatch** | Architecture describes an API that does not exist in the skill | "Library X exposes a streaming API" but skill shows only batch APIs |
+| **Protocol Contradiction** | Architecture assumes a protocol the library does not support | "Communicates via gRPC" but skill shows HTTP-only exports |
+| **Language Boundary Ignored** | Architecture assumes direct calls across language boundaries | "Calls Rust functions from TypeScript" with no FFI/IPC mechanism described |
+| **Type Incompatibility** | Architecture assumes type compatibility that does not hold | "Passes CRDT documents directly" but types are incompatible across libraries |
+
+### VS Report Integration
+
+When a VS feasibility report is available:
+- RISKY verdicts become **confirmed issues** with the VS evidence as additional citation
+- BLOCKED verdicts become **critical issues** requiring architecture redesign
+- Plausible verdicts become potential issues **only if** the VS rationale text explicitly states "no direct API evidence" or "weak evidence" — otherwise they are informational only
+
+---
+
+## Improvement Detection Rules
+
+Improvements are capability expansions — library features documented in skills but not leveraged in the architecture.
+
+### Detection Method
+
+1. For each skill, enumerate its full API surface (all exports, types, protocols)
+2. Compare against how the architecture uses that library
+3. Identify capabilities present in the skill but absent from the architecture
+
+### Improvement Classification
+
+| Improvement Type | Description | Example |
+|------------------|-------------|---------|
+| **Unused Capability** | Library has a feature the architecture does not mention | "Loro supports document CRDTs but architecture only uses data sync" |
+| **Cross-Library Synergy** | Two libraries have complementary features not combined in architecture | "Library A's event system could feed Library B's stream processor" |
+| **Alternative Pattern** | Skill documents a better pattern than the one described in architecture | "Skill shows batch API is more efficient than the per-item approach described" |
+
+---
+
+## Refinement Citation Format
+
+Every refinement (gap, issue, or improvement) MUST cite evidence:
+
+```
+**[GAP|ISSUE|IMPROVEMENT]**: {description}
+
+Evidence:
+- {skill_name} exports: `{function_name}({params}) -> {return_type}`
+- {skill_name} provides: `{type_or_protocol}`
+- Architecture states: "{quoted text from original document}"
+- {IF VS report}: VS verdict: {verdict} for {pair}
+
+Suggestion: {specific, actionable recommendation}
+```
+
+---
+
+## Preservation Rules
+
+1. **NEVER delete original content** — only add annotations and subsections
+2. **Follow original section layout** — add refinement subsections within existing sections
+3. **Use callout blocks** for issues: `> [!WARNING]` or `> [!NOTE]` format
+4. **Mark additions clearly** — prefix added subsections with "RA:" or use a refinement marker
+5. **Maintain original heading hierarchy** — refinement subsections are one level deeper than the parent

package/src/workflows/refine-architecture/steps-c/step-01-init.md

@@ -0,0 +1,188 @@
+---
+name: 'step-01-init'
+description: 'Load architecture doc, scan skills folder, load optional VS report, validate inputs'
+
+nextStepFile: './step-02-gap-analysis.md'
+refinementRulesData: '../data/refinement-rules.md'
+---
+
+# Step 1: Initialize Refinement
+
+## STEP GOAL:
+
+Load the architecture document (required), scan the skills folder to build a skill inventory with metadata, load the optional VS feasibility report for context, validate that all inputs exist and meet minimum requirements, and present an initialization summary before auto-proceeding.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- ⚙️ 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
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an architecture refinement analyst operating in Ferris Architect mode
+- ✅ Execute with analytical precision — every loaded skill must be validated against actual files
+- ✅ You enforce the zero-hallucination principle: only report skills that physically exist on disk
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on loading inputs, scanning skills, and validating prerequisites
+- 🚫 FORBIDDEN to perform any gap analysis, issue detection, or improvement suggestions
+- 🚫 No A/P menu — this is an auto-proceed init step
+- 💬 Present a clear initialization summary so downstream steps have validated inputs
+
+## EXECUTION PROTOCOLS:
+
+- Collect and validate all input documents and skill artifacts
+- Load refinement rules from {refinementRulesData} for downstream step reference
+- Auto-proceed to next step after successful initialization
+- HALT with actionable error if minimum requirements not met
+
+## CONTEXT BOUNDARIES:
+
+- This is the first step — no prior workflow state exists
+- Requires skills to have been generated by create-skill or quick-skill workflows
+- User provides architecture document path (required) and optional VS report path
+- No dependency on forge-tier — this workflow operates on skill content only
+- Requires `forge_data_folder` from config.yaml for durability state (directory is created automatically if missing)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Accept Input Documents
+
+"**Refine Architecture — Evidence-Backed Refinement**
+
+Please provide the following:
+1. **Architecture document path** (REQUIRED) — your project's architecture doc to refine
+2. **VS feasibility report path** (OPTIONAL) — from a previous [VS] Verify Stack run, for additional context"
+
+Wait for user input. Store the validated architecture document path as `architecture_doc`.
+
+**Validate architecture document:**
+- Confirm the file exists and is readable
+- If missing or unreadable: "Architecture document not found at `{path}`. Provide a valid path."
+- HALT until a valid architecture document is provided
+
+**Validate VS report (if provided):**
+- Confirm the file exists and is readable
+- If missing at user-provided path: attempt auto-probe (below) before giving up
+- Store VS report availability as `vs_report_available: true|false` and `vs_report_path`
+
+### 2. Scan Skills Folder
+
+Read the `{skills_output_folder}` directory.
+
+For each subdirectory, check for the presence of `SKILL.md` and `metadata.json`.
+
+**For each valid skill directory, extract from metadata.json:**
+- `name` — skill name
+- `language` — primary language
+- `confidence_tier` — Quick, Forge, Forge+, or Deep
+- `exports_documented` — read from `stats.exports_documented` in metadata.json (count of documented exports)
+- `source_repo` or `source_root` — original source repository
+
+**Build a skill inventory** as an internal list of all loaded skills with the fields above.
+
+**If a subdirectory lacks SKILL.md or metadata.json:**
+- Log: "Skipping `{dir_name}` — missing SKILL.md or metadata.json"
+- Do not include in inventory
+
+### 3. Validate Minimum Requirements
+
+**Check skill count:**
+- At least 1 valid skill must exist
+- If no skills found: "**Cannot proceed.** No skills found in `{skills_output_folder}`. Generate skills with [CS] Create Skill or [QS] Quick Skill, then re-run [RA]."
+- HALT workflow
+- If exactly 1 valid skill found: "⚠️ Proceeding with 1 skill. Note: gap analysis will find no gaps — pairwise analysis requires at least 2 skills. Step 02 will still execute and issue an appropriate notice. Issue detection and improvement detection will proceed normally."
+
+**Check output_folder:**
+- Verify `output_folder` was resolved from config.yaml and is non-empty
+- If undefined or empty: "**Cannot proceed.** `output_folder` is not configured in config.yaml. Add an `output_folder` path and re-run [RA]."
+- HALT workflow
+- Verify the `output_folder` directory exists. If it does not exist, create it. HALT with error if creation fails.
+
+**Check forge_data_folder:**
+- Verify `forge_data_folder` was resolved from config.yaml and is non-empty
+- If undefined or empty: "**Cannot proceed.** `forge_data_folder` is not configured in config.yaml. Add a `forge_data_folder` path to your config.yaml and re-run [RA]."
+- HALT workflow
+- Verify the `forge_data_folder` directory exists. If it does not exist, attempt to create it. If creation fails: "**Cannot proceed.** `forge_data_folder` at `{forge_data_folder}` does not exist and could not be created. Create the directory manually and re-run [RA]."
+- HALT workflow on creation failure
+
+**Check architecture document:**
+- Confirm it was loaded successfully in section 1
+- If not: HALT with error (should not reach here if section 1 validation passed)
+
+### 3b. Auto-Probe VS Report
+
+**Auto-probe VS report (if not provided by user in section 1, OR if user-provided path was invalid):**
+- Only attempt if `forge_data_folder` is non-empty and the directory exists (validated above); otherwise skip probe and set `vs_report_available: false`
+- Check for `{forge_data_folder}/feasibility-report-{project_name}.md`
+- If found: "Auto-discovered VS report at `{path}`. Loading for additional context."
+- Store `vs_report_available: true` and `vs_report_path`
+- If not found: `vs_report_available: false` — "Proceeding without VS report — issue detection will rely on skill data only."
+
+### 3c. Reset RA State File
+
+Create (or overwrite) `{forge_data_folder}/ra-state-{project_name}.md` with a fresh header:
+
+```markdown
+<!-- RA state for {project_name} — generated {current_date} -->
+```
+
+This ensures steps 02-04 append to a clean slate and context recovery in step-05 never loads stale findings from a prior run.
+
+### 4. Load Refinement Rules
+
+Load `{refinementRulesData}` for reference by downstream steps.
+
+Extract: gap detection rules, issue detection rules, improvement detection rules, citation format, and preservation rules.
+
+### 5. Display Initialization Summary
+
+"**Architecture Refinement Initialized**
+
+| Field | Value |
+|-------|-------|
+| **Architecture Doc** | {architecture_doc} |
+| **VS Report** | {vs_report_path or 'Not provided — issue detection will use skill data only'} |
+| **Skills Loaded** | {skill_count} |
+
+**Skill Inventory:**
+
+| Skill | Language | Tier | Exports |
+|-------|----------|------|---------|
+| {skill_name} | {language} | {confidence_tier} | {exports_documented} |
+
+**Proceeding to gap analysis...**"
+
+### 6. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Architecture document loaded and validated
+- VS report loaded or absence recorded
+- Skills folder scanned with SKILL.md and metadata.json validation per skill
+- At least 1 valid skill in inventory
+- Refinement rules loaded from {refinementRulesData}
+- Initialization summary displayed with skill inventory table
+- Auto-proceeded to step 02
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with no valid skills
+- Proceeding without a valid architecture document
+- Not validating SKILL.md and metadata.json existence per skill directory
+- Performing gap analysis, issue detection, or improvement suggestions in this step
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** This step validates inputs and initializes state. No analysis, no comparison, no refinement suggestions.

package/src/workflows/refine-architecture/steps-c/step-02-gap-analysis.md

@@ -0,0 +1,179 @@
+---
+name: 'step-02-gap-analysis'
+description: 'Find undocumented integration paths that the architecture does not describe but skill APIs suggest'
+
+nextStepFile: './step-03-issue-detection.md'
+refinementRulesData: '../data/refinement-rules.md'
+---
+
+# Step 2: Gap Analysis
+
+## STEP GOAL:
+
+Find undocumented integration paths — library pairs that have compatible APIs (from the generated skills) but are not described in the architecture document. For each gap, document what APIs connect and propose an architecture section describing the integration.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ 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
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an architecture refinement analyst performing gap detection
+- ✅ Every gap must cite specific APIs from the generated skills — no speculation
+- ✅ Apply the gap detection rules from {refinementRulesData} strictly
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on undocumented integration paths (gaps)
+- 🚫 FORBIDDEN to detect contradictions or issues — that is Step 03
+- 🚫 FORBIDDEN to suggest capability expansions or improvements — that is Step 04
+- 💬 Every gap MUST include evidence citations from actual skill content
+
+## EXECUTION PROTOCOLS:
+
+- Load refinement rules for gap detection criteria
+- Extract integration claims from architecture document using prose co-mention analysis
+- Generate all possible library pairs and cross-reference against architecture
+- Append gap analysis findings as workflow state for Step 05
+- Only gap detection — no issue detection, no improvement suggestions
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill inventory from Step 01, SKILL.md and metadata.json files, refinement rules
+- Focus: Finding library pairs with compatible APIs that the architecture does not describe
+- Limits: Only detect gaps — do not flag issues or suggest improvements
+- Dependencies: Step 01 must have loaded skill inventory and validated architecture document
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Reference Refinement Rules
+
+Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
+
+Extract: gap classification (Missing Integration Path, Undocumented Data Flow, Absent Bridge Layer), detection method, and citation format.
+
+### 2. Extract Integration Claims from Architecture
+
+Parse the architecture document for statements describing two or more technologies working together.
+
+**Detection method — prose-based co-mention analysis:**
+- Identify sentences or paragraphs where two or more technology names appear together
+- Look for integration verbs: "connects to", "communicates with", "wraps", "extends", "consumes", "produces", "bridges", "integrates with", "sits between", "feeds into", "receives from"
+- Look for data flow descriptions: "{A} sends data to {B}", "{A} results are consumed by {B}"
+- Look for layer boundary descriptions: "{A} at the API layer connects to {B} at the data layer"
+
+**CRITICAL:** Do NOT parse Mermaid diagram syntax. Use only prose text for co-mention detection.
+
+**Mermaid Limitation Warning:** If `` ```mermaid `` blocks are present in the architecture document, inform the user: "Integration paths documented exclusively in Mermaid diagrams are excluded from co-mention analysis and may appear as false-positive gaps. Consider adding prose descriptions for diagram-only integration paths." Display this warning informatively and immediately continue — this does not halt or modify the analysis sequence.
+
+**Build documented pairs list:**
+- Each pair: `{library_a, library_b, architectural_context}`
+- `architectural_context`: the quoted text or paraphrased description of their relationship
+
+### 3. Generate All Possible Library Pairs
+
+From the skill inventory, generate all unique combinations of library pairs.
+
+For N skills, this produces N*(N-1)/2 unique pairs.
+
+### 4. Load Skill API Surfaces for Cross-Reference
+
+For each library in the skill inventory, load the skill artifacts:
+
+**From SKILL.md, extract:**
+- Exported functions and their signatures
+- Exported types, interfaces, and classes
+- Protocol indicators (HTTP, gRPC, WebSocket, message queue, file I/O, IPC)
+- Data format indicators (JSON, protobuf, CSV, binary, streaming)
+
+**From metadata.json, extract:**
+- `language` — primary programming language
+- `exports` — export count and names
+
+### 5. Cross-Reference: Identify Gaps
+
+For each possible library pair NOT already documented in the architecture:
+
+**Check API compatibility:**
+- Does Library A export types or data that Library B can consume?
+- Do both libraries share a compatible protocol or data format?
+- Are they in the same language or is there a bridge mechanism available?
+
+**If compatible APIs exist but NO architecture mention:**
+- Classify the gap type (Missing Integration Path, Undocumented Data Flow, or Absent Bridge Layer)
+- Document the connecting APIs from both skills
+- Propose a brief architecture section describing the integration
+
+**Apply the citation format from {refinementRulesData}:**
+```
+**[GAP]**: {description}
+
+Evidence:
+- {skill_a} exports: `{function}({params}) -> {return_type}`
+- {skill_b} accepts: `{function}({params})`
+- Compatibility: {explanation}
+
+Suggestion: {proposed architecture section content}
+```
+
+**If no compatible APIs:** Skip this pair — not all pairs need to integrate.
+
+### 6. Display Gap Analysis Results
+
+"**Pass 1: Gap Analysis — Undocumented Integration Paths**
+
+**Gaps Found:** {count}
+
+{IF gaps found:}
+| # | Library A | Library B | Gap Type | Connecting APIs |
+|---|-----------|-----------|----------|-----------------|
+| {n} | {lib_a} | {lib_b} | {gap_type} | {brief API description} |
+
+{For each gap, display the full citation with evidence and suggestion}
+
+{IF no gaps found AND N > 1:}
+**No undocumented integration paths detected.** The architecture document covers all compatible library pairs.
+
+{IF no gaps found AND N == 1:}
+**⚠️ Gap analysis skipped — only 1 skill loaded.** Pairwise integration analysis requires at least 2 skills. If the architecture references multiple libraries, those without a matching skill are invisible to gap analysis. **Recommendation:** Generate skills for all architecture libraries with [CS] or [QS] before running [RA] for comprehensive gap detection.
+
+**Proceeding to issue detection (still produces value with 1 skill)...**"
+
+Store all gap findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-GAPS] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted gap findings** (full citation blocks with evidence and suggestions, not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+
+### 7. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Refinement rules loaded from {refinementRulesData}
+- Integration claims extracted from architecture document using prose co-mention analysis
+- All possible library pairs generated from skill inventory
+- Skill API surfaces loaded for cross-reference
+- Each gap includes evidence citations from actual skill content
+- Gap analysis results displayed with count and details
+- Gap findings stored as workflow state for Step 05
+- Auto-proceeded to step 03
+
+### ❌ SYSTEM FAILURE:
+
+- Inventing APIs not present in the actual skills
+- Flagging contradictions or issues (that is Step 03)
+- Suggesting capability improvements (that is Step 04)
+- Gaps without evidence citations from generated skills
+- Parsing Mermaid diagrams instead of using prose-based co-mention analysis
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/refine-architecture/steps-c/step-03-issue-detection.md

@@ -0,0 +1,182 @@
+---
+name: 'step-03-issue-detection'
+description: 'Find contradictions between architecture claims and verified API reality from skills and optional VS report'
+
+nextStepFile: './step-04-improvements.md'
+refinementRulesData: '../data/refinement-rules.md'
+---
+
+# Step 3: Issue Detection
+
+## STEP GOAL:
+
+Find contradictions between what the architecture document claims and what the generated skills reveal about actual API surfaces. Detect language boundary issues not addressed, protocol mismatches assumed away, and missing bridge layers. If a VS feasibility report is available, incorporate RISKY and BLOCKED verdicts as confirmed issues.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ 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
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an architecture refinement analyst performing contradiction detection
+- ✅ Every issue must cite evidence from actual skill content AND the architecture claim it contradicts
+- ✅ Apply the issue detection rules from {refinementRulesData} strictly
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on contradictions between architecture claims and skill API reality
+- 🚫 FORBIDDEN to detect undocumented integration paths — that was Step 02
+- 🚫 FORBIDDEN to suggest capability expansions — that is Step 04
+- 💬 Every issue MUST cite both the architecture claim AND the contradicting skill evidence
+
+## EXECUTION PROTOCOLS:
+
+- Load refinement rules for issue detection criteria
+- Extract all integration claims from the architecture document
+- Verify each claim against skill API surfaces
+- Incorporate VS report verdicts if available
+- Append issue findings as workflow state for Step 05
+- Only issue detection — no gap analysis, no improvement suggestions
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill inventory and SKILL.md files, VS feasibility report (if provided), refinement rules
+- Focus: Finding contradictions between documented claims and verified API reality
+- Limits: Only detect issues — do not fill gaps or suggest improvements
+- Dependencies: Step 01 (skill inventory, architecture doc, VS report status), Step 02 (gap analysis complete)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Reference Refinement Rules
+
+Use the refinement rules loaded in Step 01 from `{refinementRulesData}`. If not available in context, reload from `{refinementRulesData}`.
+
+Extract: issue classification (API Mismatch, Protocol Contradiction, Language Boundary Ignored, Type Incompatibility), VS report integration rules, and citation format.
+
+### 2. Extract Integration Claims from Architecture
+
+Parse the architecture document for specific claims about how technologies interact.
+
+**Claim types to extract:**
+- **API claims:** "Library X provides/exposes/exports {function/endpoint}"
+- **Protocol claims:** "Library X communicates via {protocol}"
+- **Data flow claims:** "Data flows from X to Y as {format}"
+- **Integration claims:** "X and Y integrate through {mechanism}"
+- **Capability claims:** "Library X handles {capability}"
+
+For each claim, record:
+- The exact text or paraphrase from the architecture
+- The section where it appears
+- The libraries referenced
+
+### 3. Verify Claims Against Skill API Surfaces
+
+For each extracted claim, load the relevant skill(s) and check:
+
+**API Mismatch check:**
+- Does the claimed API actually exist in the skill's export list?
+- Does the function signature match what the architecture describes?
+- If the architecture describes an API that does not appear in the skill: flag as issue
+
+**Protocol Contradiction check:**
+- Does the skill document the protocol the architecture assumes?
+- If the architecture claims gRPC but the skill shows HTTP-only: flag as issue
+
+**Language Boundary check:**
+- If two libraries are in different languages, does the architecture describe a bridge mechanism?
+- If the architecture assumes direct calls across language boundaries without FFI/IPC: flag as issue
+
+**Type Incompatibility check:**
+- Does the architecture assume type compatibility that the skills contradict?
+- If Library A exports Type X but the architecture claims Library B consumes it, and Library B expects Type Y: flag as issue
+
+### 4. Incorporate VS Report (If Available)
+
+If `vs_report_available` is true:
+
+**Load the VS feasibility report and extract verdicts:**
+- **Risky verdicts** (match case-insensitively: "Risky", "RISKY", "risky"): Promote to confirmed issues with the VS evidence as additional citation
+- **Blocked verdicts** (match case-insensitively: "Blocked", "BLOCKED", "blocked"): Promote to critical issues requiring architecture redesign
+- **Plausible verdicts:** Note informatively — Plausible is not an issue by itself. Only flag as a potential issue if the VS rationale text explicitly states "no direct API evidence" or "weak evidence"
+
+**For each VS-sourced issue, include dual citations:**
+- Evidence from the skill content
+- Verdict and rationale from the VS report
+
+If `vs_report_available` is false: Skip this section. Issue detection proceeds with skill data only.
+
+### 5. Document Each Issue
+
+For each detected issue, apply the citation format from {refinementRulesData}:
+
+```
+**[ISSUE]**: {description}
+
+Architecture states: "{quoted claim from original document}" (Section: {section_name})
+Skill reality: {skill_name} exports: `{actual_api}` — {explanation of contradiction}
+{IF VS report}: VS verdict: {Risky|Blocked} for {pair} — {VS rationale}
+
+Suggestion: {specific correction with API evidence}
+```
+
+**Severity classification:**
+- **Critical:** Blocked VS verdicts, fundamental language barriers with no bridge
+- **Major:** Risky VS verdicts, protocol mismatches, missing bridge layers
+- **Minor:** Plausible VS verdicts where the VS rationale explicitly states "no direct API evidence" or "weak evidence", minor type differences with easy conversion
+
+### 6. Display Issue Detection Results
+
+"**Pass 2: Issue Detection — Architecture vs. API Reality**
+
+**Issues Found:** {count} ({critical_count} critical, {major_count} major, {minor_count} minor)
+
+{IF issues found:}
+| # | Libraries | Issue Type | Severity | Summary |
+|---|-----------|-----------|----------|---------|
+| {n} | {libs} | {issue_type} | {severity} | {brief description} |
+
+{For each issue, display the full citation with evidence and suggestion}
+
+{IF no issues found:}
+**No contradictions detected.** Architecture claims align with verified skill API surfaces.
+
+**Proceeding to improvement detection...**"
+
+Store all issue findings as workflow state for Step 05. To ensure durability across long runs, also append a `<!-- [RA-ISSUES] ... -->` comment block to `{forge_data_folder}/ra-state-{project_name}.md` containing the **complete formatted issue findings** (full citation blocks with architecture claims, skill evidence, VS verdicts, severity, and suggestions — not just counts) — Step 05 can read this back if context degrades. **Do NOT write to `{output_folder}/refined-architecture-{project_name}.md` — that file is created only in step-05.**
+
+### 7. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Refinement rules loaded from {refinementRulesData}
+- All integration claims extracted from architecture document
+- Each claim verified against actual skill API surfaces
+- VS report verdicts incorporated if report was provided
+- Every issue includes both architecture citation AND contradicting skill evidence
+- Issues classified by severity (Critical, Major, Minor)
+- Issue detection results displayed with count and details
+- Issue findings stored as workflow state for Step 05
+- Auto-proceeded to step 04
+
+### ❌ SYSTEM FAILURE:
+
+- Issues without evidence from actual skills (speculation)
+- Not citing the architecture claim that is contradicted
+- Filling gaps (that was Step 02) or suggesting improvements (that is Step 04)
+- Ignoring VS report verdicts when the report was provided
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.