Review implementation fidelity against specifications by comparing actual code to spec requirements. Identifies deviations, assesses impact, and generates compliance reports for tasks, phases, or entire specs.
Compares code implementation against specification requirements to identify deviations and generate compliance reports.
npx claudepluginhub foundry-works/claude-foundryThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/assessment.mdreferences/best-practices.mdreferences/errors.mdreferences/examples.mdreferences/integration.mdreferences/long-running.mdreferences/lsp-integration.mdreferences/querying.mdreferences/report.mdreferences/review-types.mdreferences/subagent.mdreferences/workflow.mdThe foundry-review skill compares actual implementation against SDD specification requirements. It uses LSP for structural verification and MCP for AI-powered deviation analysis.
Part of the Spec-Driven Development quality assurance family:
foundry-spec → foundry-implement → [CODE] → foundry-review (this skill)
Use when:
Do NOT use for:
foundry-spec)foundry-implement)
[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
This skill uses the Foundry MCP server with router+action pattern: mcp__plugin_foundry_foundry-mcp__<router> with action="<action>".
Critical Rules:
Read() on spec JSON filescat, grep, jq) on specs| Router | Action | Purpose |
|---|---|---|
review | fidelity | Run AI-powered fidelity analysis |
task | query | List tasks for review scope |
task | info | Get task details and acceptance criteria |
spec | diff | Compare spec versions to understand changes |
spec | history | View spec modification timeline |
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:
The fidelity review workflow integrates LSP verification with MCP AI analysis:
For unfamiliar code, use Explore subagent to find implementation files:
Explore agent (medium thoroughness): Find all files in phase-1, related tests, config files
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
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.
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.
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.
| Operation | When to Use | Purpose |
|---|---|---|
documentSymbol | Pre-check | List all symbols in a file for structural verification |
workspaceSymbol | Pre-check | Find symbols across codebase |
hover | During review | Get type info and documentation |
goToDefinition | Investigation | Trace where symbols are defined |
findReferences | Investigation | Find all usages of a symbol |
incomingCalls | Investigation | Find what calls a function |
outgoingCalls | Investigation | Find what a function calls |
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
| Type | Scope | When to Use |
|---|---|---|
| Phase Review | 3-10 tasks | Phase completion checkpoints |
| Task Review | 1 file | Critical task validation, high-risk implementations |
For detailed workflow per review type, see
references/review-types.md
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.
| Category | Meaning |
|---|---|
| Exact Match | Implementation precisely matches specification |
| Minor Deviation | Small differences with no functional impact |
| Major Deviation | Significant differences affecting functionality |
| Missing | Specified features not implemented |
This skill may take up to 5 minutes. The MCP tool handles timeout internally.
Never use run_in_background=True with frequent polling.
Skill(foundry:foundry-review) "Review phase phase-1 in spec user-auth-001"
For comprehensive documentation including:
references/long-running.mdreferences/review-types.mdreferences/lsp-integration.mdreferences/querying.mdreferences/workflow.mdreferences/report.mdreferences/integration.mdreferences/assessment.mdreferences/examples.mdreferences/errors.mdreferences/best-practices.mdreferences/subagent.mdActivates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.