expertise-file-design

# Expertise File Design

Guide for designing YAML expertise files that serve as mental models for agent experts.

## MANDATORY: Act-Learn-Reuse Context

Expertise files are **mental models**, NOT sources of truth. They:

- Accelerate agent execution by pre-loading domain knowledge
- Are maintained by self-improve prompts, not humans
- Validate against the actual codebase (source of truth)
- Have enforced line limits to protect context windows

## When to Use

- Creating mental models for new domain-specific agents
- Defining expertise schema structures (YAML)
- Structuring knowledge for Act-Learn-Reuse workflows
- Reviewing or auditing existing expertise file designs
- Setting up line limits and section priorities

## Expertise File Structure

### Core Template

```yaml
# {domain}/expertise.yaml
# Mental model for {domain} agent expert
# Last updated: {timestamp}
# Lines: {current}/{max}

overview:
  description: "Brief description of this domain"
  primary_technology: "Main tech/framework"
  architecture_pattern: "Key pattern used"

core_implementation:
  main_module:
    file: "path/to/main/file.ext"
    lines: approximate_line_count
    purpose: "What this module does"
    key_exports:
      - name: "FunctionOrClass"
        type: "function|class|constant"
        purpose: "Brief description"

  supporting_modules:
    - file: "path/to/support.ext"
      purpose: "Supporting functionality"

schema_structure:  # For database/API domains
  entities:
    entity_name:
      fields:
        - name: "field_name"
          type: "data_type"
          constraints: "nullable, unique, etc."
      relationships:
        - target: "other_entity"
          type: "one-to-many|many-to-many"

key_operations:
  operation_category:
    operation_name:
      function: "function_name"
      file: "path/to/file.ext"
      signature: "func(param: Type) -> ReturnType"
      logic: "Brief description of what it does"
      edge_cases:
        - "Important edge case 1"
        - "Importa