/validate-expertise

Validate agent expertise files to ensure they haven't drifted from the codebase and remain current.

Quick Start

Copy/agileflow:validate-expertise

Validates all expertise files. You can also validate a specific domain:

Copy/agileflow:validate-expertise DOMAIN=database

Parameters

Validation Checks

The command performs four critical validation checks on each expertise file:

1. File Path Drift

Checks that all file paths referenced in the expertise file still exist in the codebase. Detects when documented files have been moved, renamed, or deleted.

Example: If expertise.yaml references src/old/database.ts but that file no longer exists, it flags this as drift.

2. Stale Learnings

Flags expertise files that haven't been updated in 30 or more days. Expertise that's not regularly maintained becomes outdated and less reliable.

Warning: Files not updated in 30+ days are marked for review and update.

3. File Size Check

Warns if an expertise file exceeds 200 lines. Oversized files are hard to maintain and should be split into smaller, focused documents.

Recommendation: Keep expertise files under 200 lines for better maintainability.

4. Required Sections

Verifies that the expertise.yaml file contains all required sections:

• domain: Domain identifier
• mental_models: At least one mental model (core concepts)
• learnings: Learning history (can be empty initially)
• key_files: Important files for this domain
• patterns: Common patterns and anti-patterns

Examples

Validate All Expertise Files

Copy/agileflow:validate-expertise

Runs validation on all expertise files in .agileflow/experts/ directory.

Validate Specific Domain

Copy/agileflow:validate-expertise DOMAIN=database

Validates only the database domain expertise file.

Check Another Domain

Copy/agileflow:validate-expertise DOMAIN=api

Validates only the API domain expertise file.

Output Format

The command produces a detailed validation report:

Copy======================================
EXPERTISE VALIDATION REPORT
======================================
 
Validating: database
  [PASS] File exists: expertise.yaml
  [PASS] Required sections present
  [WARN] 2 stale learnings (>30 days)
  [FAIL] DRIFT: src/old/database.ts not found
 
Validating: api
  [PASS] All checks passed
 
Validating: frontend
  [WARN] File size: 287 lines (recommend \<200)
 
--------------------------------------
SUMMARY
--------------------------------------
Total domains: 25
Passed: 23
Warnings: 1
Failures: 1
 
RECOMMENDED ACTIONS:
1. Update database expertise - remove reference to src/old/database.ts
2. Split frontend expertise - reduce from 287 to \<200 lines
3. Review stale learnings in database domain

Status Indicators

Common Issues and Solutions

When to Run

Run expertise validation:

• After session start: Optional as part of system health checks (can be configured as a hook)
• Before major releases: Ensure all expertise is current and accurate
• After large refactors: Validate that file references still point to valid locations
• Periodically: Run monthly/quarterly to maintain expertise currency
• When modifying expertise: Validate changes before committing

Expertise File Location

Expertise files are stored at:

Copy.agileflow/experts/{domain}/expertise.yaml

For example:

• .agileflow/experts/database/expertise.yaml
• .agileflow/experts/api/expertise.yaml
• .agileflow/experts/frontend/expertise.yaml

Success Criteria

A healthy expertise file should:

• ✅ All referenced files exist in the codebase
• ✅ Updated within the last 30 days
• ✅ Under 200 lines
• ✅ Contains all required sections (domain, mental_models, learnings, key_files, patterns)

Integration with Your Workflow

You can configure expertise validation to run automatically:

Copy/agileflow:configure --enable=expertise-validation

This adds a SessionStart hook that validates expertise on each session start and alerts you to issues.

Drift Detection Details

File path drift is the most critical issue detected. The command looks for file references in the format:

• src/... - Source code files
• packages/... - Monorepo packages
• lib/... - Library files

If these paths no longer exist, they're flagged for immediate attention and removal.

Related Commands

• /configure - Configure validation to run automatically
• /diagnose - Run system health diagnostics
• /agent - Onboard new agents (creates expertise files)
• /help - View all available commands