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.

## Current State

- **Planned design docs**: !'ls design_docs/planned/ 2>/dev/null | head -10'
- **Implemented design docs**: !'ls design_docs/implemented/ 2>/dev/null | tail -5'
- **Branch**: !'git branch --show-current'
- **Recent changes**: !'git log --oneline -5'

> **Use the data above first.** Only re-run these commands manually if the injected context is empty or you need to refresh after making changes.

## Quick Start

**Most common usage:**
```bash
# 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

```bash
# 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:**

```markdown
# 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)
```

## Auditing Agent-Executed Work

When auditing sprint executor or other agent work against design specs, also verify the agent's conversation history to detect skipped tasks:

```bash
# View agent reasoning per turn (grouped text + tool calls)
ailang coordinator logs <task-id> --limit 1000 --json | python3 -c "
import json, sys
data = json.load(sys.stdin)
events = data.get('events', [])
turns = {}; tools = {}
for evt in events:
    tn = evt.get('turn_num', 0); st = evt.get('stream_type', '')
    if st == 'text': turns.setdefault(tn, []).append(evt.get('text', ''))
    elif st == 'tool_use': tools.setdefault(tn, []).append(evt.get('tool_name', '?'))
for tn in sorted(turns.keys()):
    text = ''.join(turns[tn]).strip()
    if len(text) > 20:
        print(f'=== Turn {tn} (tools: {\", \".join(tools.get(tn, []))}) ===')
        print(text[:600]); print()
"

# View chain execution flow (recommended)
ailang chains view <chain-id> --spans
ailang chains tree <chain-id> --detailed

# View tool usage timeline (requires server)
ailang dashboard spans --task-id <task-id> --limit 200

# View git changes made by agent
ailang coordinator diff <task-id>
```

**Cross-reference checklist:**
- [ ] Sprint plan acceptance criteria vs actual git diff
- [ ] Did agent modify `internal/` code or just create examples/docs?
- [ ] What model was used? (Check `executor.model` in spans - Haiku may be too weak for compiler tasks)
- [ ] Did it run `ailang run` (runtime test) or just `ailang check` (compile test)?
- [ ] Did it mark tasks as "already working" without verifying the specific bug scenario?

## 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