Implementation Fidelity Review Skill

Table of Contents

• Overview
• Skill Family
• When to Use
• MCP Tooling
• Core Workflow
• LSP Operations Quick Reference
• Essential Commands
• Review Types
• Assessment Categories
• Long-Running Operations
• Example Invocation

Overview

The foundry-review skill compares actual implementation against SDD specification requirements. It uses LSP for structural verification and MCP for AI-powered deviation analysis.

Skill Family

Part of the Spec-Driven Development quality assurance family:

foundry-spec → foundry-implement → [CODE] → foundry-review (this skill)

When to Use This Skill

Use when:

• Verifying implementation matches specification requirements
• Identifying deviations between plan and actual code
• Reviewing pull requests for spec compliance
• Auditing completed phases or tasks

Do NOT use for:

• Creating specifications (use foundry-spec)
• Finding next tasks or tracking progress (use foundry-implement)
• Running tests (run directly via Bash)

Flow

[x?]=decision · (GATE)=user approval · →=sequence · ↻=loop · §=section ref

- **Entry** → [Familiar with code?]
  - [no] → Explore subagent
  - [else] → skip
  - Spec changes → `spec action="diff"` → `spec action="history"`
  - LSP pre-check → `documentSymbol`
    - [structures exist?] → continue
    - [else] → Early exit with findings → **Exit**: Report
  - MCP review → `fidelity action="review"` → Scope: phase or task
    - [deviations found?] → LSP investigate → `goToDefinition` → `findReferences` → `incomingCalls`
  - Assess deviation: Exact, Minor, Major, Missing
  - **Exit** → Report with recommendations

MCP Tooling

This skill uses the Foundry MCP server with router+action pattern: mcp__plugin_foundry_foundry-mcp__<router> with action="<action>".

Critical Rules:

• ALWAYS use MCP tools for spec operations
• NEVER use Read() on spec JSON files
• NEVER use shell commands (cat, grep, jq) on specs

Router Actions

Spec Comparison for Fidelity Context

Use spec:diff and spec:history to understand what changed before reviewing implementation:

# See what changed since last review
mcp__plugin_foundry_foundry-mcp__spec action="diff" spec_id="{spec-id}" compare_to="specs/.backups/{spec-id}-previous.json"

# View modification history to understand evolution
mcp__plugin_foundry_foundry-mcp__spec action="history" spec_id="{spec-id}" limit=5

Why this helps fidelity review:

• diff: Identifies which requirements changed, helping focus review on modified tasks
• history: Shows when requirements were added/modified, explaining apparent deviations that were actually spec updates

Core Workflow

The fidelity review workflow integrates LSP verification with MCP AI analysis:

Step 1: Gather Context (Optional)

For unfamiliar code, use Explore subagent to find implementation files:

Explore agent (medium thoroughness): Find all files in phase-1, related tests, config files

Step 2: Check Spec Changes

Before reviewing, understand what changed in the spec since the last review:

# Check recent spec modifications
mcp__plugin_foundry_foundry-mcp__spec action="history" spec_id="{spec-id}" limit=5

# Compare current spec against last backup
mcp__plugin_foundry_foundry-mcp__spec action="diff" spec_id="{spec-id}" compare_to="specs/.backups/{spec-id}-last-review.json"

Deviation assessment using diff:

📊 Spec Diff: user-auth-001

Tasks:
  ~ task-1-2: Acceptance criteria updated (added "support OAuth2")
  + task-1-4: New task added after initial implementation

Use this to:
- Focus review on changed requirements (task-1-2)
- Flag new tasks as "not yet implemented" rather than "deviation" (task-1-4)
- Explain apparent deviations that reflect spec evolution

Step 3: LSP Structural Pre-Check

Before the AI review, verify structural requirements with LSP:

# Get symbols in implementation file
symbols = LSP(operation="documentSymbol", filePath="src/auth/service.py", line=1, character=1)

# Compare against spec: expects AuthService with login(), logout(), refresh_token()
# Identify missing symbols before expensive AI review

Why: Catches missing implementations in seconds before 5-minute AI review.

Step 4: MCP Fidelity Review

Run the AI-powered fidelity analysis:

# Phase review
mcp__plugin_foundry_foundry-mcp__review action="fidelity" spec_id="{spec-id}" phase_id="{phase-id}"

# Task review
mcp__plugin_foundry_foundry-mcp__review action="fidelity" spec_id="{spec-id}" task_id="{task-id}"

The MCP tool handles spec loading, implementation analysis, AI consultation, and report generation.

Step 5: LSP-Assisted Investigation

For deviations found, use LSP to investigate:

# Trace deviation origin
definition = LSP(operation="goToDefinition", filePath="src/auth/service.py", line=45, character=10)

# Find what depends on deviated code
calls = LSP(operation="incomingCalls", filePath="src/auth/service.py", line=45, character=10)

# Assess blast radius
refs = LSP(operation="findReferences", filePath="src/auth/service.py", line=45, character=10)

Why: Understand deviation impact before recommending fixes.

CRITICAL: Read references/lsp-integration.md before LSP investigation. Contains required operation patterns.

LSP Operations Quick Reference

Essential Commands

Query tasks before review:

mcp__plugin_foundry_foundry-mcp__task action="query" spec_id="{spec-id}" parent="{phase-id}"

Phase review:

mcp__plugin_foundry_foundry-mcp__review action="fidelity" spec_id="{spec-id}" phase_id="{phase-id}"

Task review:

mcp__plugin_foundry_foundry-mcp__review action="fidelity" spec_id="{spec-id}" task_id="{task-id}"

For query patterns and anti-patterns, see references/querying.md

Review Types

For detailed workflow per review type, see references/review-types.md

Plan-Enhanced Review

When a spec has a linked plan_path, fidelity review automatically includes spec-vs-plan comparison. This is not a separate review type — it augments the standard phase or task review with additional plan alignment checks.

Auto-triggered when: Spec metadata contains plan_path No user action needed: The MCP tool detects plan linkage and enhances the review automatically

The response includes a plan_enhanced boolean indicating whether plan comparison was performed.

Fidelity Assessment Categories

Long-Running Operations

This skill may take up to 5 minutes. The MCP tool handles timeout internally.

Never use run_in_background=True with frequent polling.

Example Invocation

Skill(foundry:foundry-review) "Review phase phase-1 in spec user-auth-001"

Detailed Reference

For comprehensive documentation including:

• Long-running operations guidance → references/long-running.md
• Review types → references/review-types.md
• LSP integration patterns → references/lsp-integration.md
• Querying spec data → references/querying.md
• Workflow steps → references/workflow.md
• Report structure → references/report.md
• SDD workflow integration → references/integration.md
• Assessment categories → references/assessment.md
• Examples → references/examples.md
• Error handling → references/errors.md
• Best practices → references/best-practices.md
• Subagent patterns → references/subagent.md