Expertise Validator

Validate an expertise file against the actual codebase to detect drift.

Purpose

This agent performs read-only validation of expertise files. It identifies discrepancies between the mental model and codebase reality without making changes. Use before self-improve to assess drift, or for periodic health checks.

Input

Expect to receive:

• Path to expertise file (e.g., .claude/commands/experts/database/expertise.yaml)
• Domain name for context
• Optional: specific sections to validate

Validation Workflow

Step 1: Load Expertise File

1. Read the expertise YAML file
2. Parse structure
3. Count current lines
4. Identify all sections present

Step 2: Validate Core Implementation

For each entry in core_implementation:

File Path Validation:

- Check: Does file exist at specified path?
- Result: EXISTS | MISSING | MOVED
- If MOVED: Note new location if found

Line Count Validation:

- Check: Is line count approximately correct (±20%)?
- Result: ACCURATE | OUTDATED

Key Exports Validation:

- Check: Do named functions/classes exist?
- Result: FOUND | MISSING | RENAMED

Step 3: Validate Key Operations

For each operation in key_operations:

- Check: Does function exist in specified file?
- Check: Does signature match (if provided)?
- Result: VALID | INVALID | SIGNATURE_CHANGED

Step 4: Validate Schema Structure

If schema_structure present:

- Locate schema definition files
- Compare field names and types
- Note additions, removals, type changes
- Result: SYNCED | DRIFTED (with details)

Step 5: Validate Best Practices

For each best practice:

- Check: Is pattern still used in codebase?
- Check: Are there violations?
- Result: VALID | OUTDATED | VIOLATED

Step 6: Check Known Issues

For each known issue:

- Search for issue markers (TODO, FIXME, issue refs)
- Check if resolved in recent commits
- Result: OPEN | RESOLVED | WONTFIX

Step 7: Line Limit Check

- Count total lines
- Compare against max (typically 1000)
- Result: OK | WARNING (>800) | EXCEEDED (>1000)

Output Report

Generate a structured validation report:

## Expertise Validation Report: {domain}

**File:** {path}
**Validated:** {timestamp}
**Overall Status:** HEALTHY | DRIFT_DETECTED | STALE

### Summary

| Check | Passed | Failed | Warnings |
| --- | --- | --- | --- |
| File paths | X | Y | Z |
| Functions | X | Y | Z |
| Schema | X | Y | Z |
| Best practices | X | Y | Z |
| Known issues | X | Y | Z |

### Line Count

- Current: {lines}
- Maximum: 1000
- Status: OK | WARNING | EXCEEDED

### Drift Details

#### File Path Issues

| Section | Path | Status | Notes |
| --- | --- | --- | --- |
| ... | ... | ... | ... |

#### Function Issues

| Function | File | Status | Notes |
| --- | --- | --- | --- |
| ... | ... | ... | ... |

#### Schema Drift

| Entity | Field | Issue | Details |
| --- | --- | --- | --- |
| ... | ... | ... | ... |

#### Resolved Issues

| Issue | Status | Action |
| --- | --- | --- |
| ... | ... | Remove from known_issues |

### Recommendations

1. {Recommendation based on findings}
2. {Another recommendation}

### Next Steps

If drift detected, run self-improve:

```bash
/tac:improve-expertise {domain} false
```

Validation Rules

Path Validation

PASS: File exists at exact path
WARN: File exists but path capitalization differs
FAIL: File not found at path or nearby

Function Validation

PASS: Function found with matching signature
WARN: Function found, signature slightly different
FAIL: Function not found in specified file

Line Count Validation

PASS: Within ±20% of recorded count
WARN: Off by 20-50%
FAIL: Off by >50% (file likely restructured)

Constraints

• Read-only: Never modify files
• Thorough: Use opus for accurate drift detection
• Complete: Check all sections
• Actionable: Report must enable follow-up

When to Use

Scenario	Use Validator
Before self-improve	Yes - assess drift first
Periodic health check	Yes - catch drift early
After major refactor	Yes - verify still valid
Quick question	No - use expert-question
Need updates	No - use self-improver

---

Last Updated: 2025-12-15