design-spec-auditor

name	Design Spec Auditor
description	Verify code implementation aligns with design specifications. Use after implementing features, during code reviews, or when refactoring to ensure architectural compliance. Compares design docs with actual code.

Design Spec Auditor

Verify that code implementations match their design specifications and identify inconsistencies.

Quick Start

Most common usage:

# User says: "Check if parser matches the design doc"
# This skill will:
# 1. Read design doc (design_docs/planned/ or implemented/)
# 2. Read corresponding code
# 3. Compare and identify discrepancies
# 4. Generate compliance report

When to Use This Skill

Invoke when user says:

• "Check if implementation matches design"
• "Audit the parser against its spec"
• "Verify code compliance"
• "Review design alignment"

Also use:

• After implementing new features
• During code reviews
• After refactoring

Workflow

Step 1: Identify Design Documents

# Find relevant design docs
ls design_docs/planned/     # Planned features
ls design_docs/implemented/ # Completed features

# For a specific feature:
find design_docs -name "*parser*" -o -name "*type*"

Step 2: Map Design to Code

For each design component, identify:

Design Element	Code Location
Module boundaries	internal/ package structure
Interface contracts	Type definitions, function signatures
Data flow	Function call chains
Error handling	Error types and propagation

Step 3: Systematic Comparison

Check each design requirement:

1. Architectural decisions

   • Are module boundaries respected?
   • Are dependencies one-way as specified?

2. Interface contracts

   • Do function signatures match spec?
   • Are return types correct?

3. Behavioral requirements

   • Does error handling match spec?
   • Are edge cases covered?

4. Performance requirements

   • Are complexity bounds met?
   • Are resource limits respected?

Step 4: Categorize Discrepancies

Severity	Definition	Action
Critical	Breaks core architectural principles	Fix code immediately
Major	Significant behavioral deviation	Fix code or update design
Minor	Small inconsistency	Document and track
Naming	Terminology mismatch	Update docs for clarity
Missing	Specified but not implemented	Add to backlog
Extra	Implemented but not specified	Update design doc

Step 5: Generate Report

Report format:

# Design Compliance Audit: [Feature Name]

## Summary
- **Compliance**: 85%
- **Critical Issues**: 0
- **Major Issues**: 2
- **Minor Issues**: 5

## Critical Issues
(none)

## Major Issues

### Issue 1: Missing error propagation
- **Design doc**: design_docs/implemented/v0_3_0/effects.md, Section 3.2
- **Code location**: internal/effects/handler.go:145-160
- **Discrepancy**: Design specifies errors should propagate to caller; code silently ignores
- **Recommendation**: Fix code to match design

## Minor Issues
...

## Recommendations
1. Update internal/effects/handler.go to propagate errors
2. Add missing test cases for edge conditions
3. Update design doc section 4.1 to reflect actual behavior

Comparison Checklist

Use this checklist for each audit:

• Module structure matches design
• Public APIs match signatures in spec
• Error types and handling match spec
• Data structures match definitions
• Invariants are enforced
• Performance requirements met
• Tests cover specified scenarios
• Edge cases handled as specified

Common Discrepancy Patterns

Intentional Deviations

Sometimes code legitimately differs from design:

• Performance optimizations
• Discovered constraints during implementation
• Pragmatic simplifications

Action: Update design doc to reflect reality

Unintentional Oversights

• Forgot to implement a feature
• Misunderstood requirement
• Copy-paste errors

Action: Fix code to match design

Design Drift

Design docs lag behind rapid development:

• Features added without updating docs
• Refactoring changed structure

Action: Update design docs

Example Session

User: "Check if the type system matches its design"

Response:

Auditing type system against design_docs/implemented/v0_3_0/type-system.md...

Reading design doc... Found 15 specified behaviors
Reading code in internal/types/... Found 12 implemented

## Compliance Report: Type System

### Summary
- Compliance: 80%
- Critical: 0
- Major: 1
- Minor: 2

### Major Issues

1. **Row polymorphism extension**
   - Design: Section 4.2 specifies record extension syntax `{...r, x: T}`
   - Code: internal/types/unify.go only supports field access, not extension
   - Action: Implement extension or mark as "planned" in docs

### Minor Issues

1. **Naming**: Design uses "type variable", code uses "tyvar"
2. **Extra**: Code has `TypeCache` not mentioned in design

### Recommendations
1. Implement row extension or update roadmap
2. Add TypeCache to design doc (performance optimization)

Tips

• Newer docs supersede older ones - check dates
• Some deviations are intentional - document them
• Focus on behavior, not exact wording
• Consider evolution - designs change over time