prompt-maintenance

Prompt Maintenance

Manages prompt template health across the project.

Commands

/prompt-maintenance audit

Full analysis of all configured sources.

Process:

1. Load .prompt-maintenance.json from project root
2. For each source:
   • Scan files matching pattern
   • Parse headers and extract metadata
   • Build dependency graph from {% include %} statements
   • Scan Python files for direct template references (PromptLoader, get_template)
   • Validate against rules in references/validation-rules.md
3. Report errors and warnings
4. Show statistics

Output Format:

prompt-maintenance audit

Scanning apps/ana-service/app/templates/...

✓ 68 templates analyzed
✓ 156 dependencies mapped

ERRORS (N):
  ✗ path/file.jinja2:line - Error description

WARNINGS (N):
  ⚠ path/file.jinja2 - Warning description

Stats:
  By domain: lesson (12), brainstorm (8), _shared (4), ...
  Orphans: 2 templates not referenced

Run '/prompt-maintenance sync' to update catalog.

/prompt-maintenance sync

Regenerate documentation artifacts.

Process:

1. Run full audit (silent mode)
2. Generate prompts.json for each source
3. Generate individual catalog per source
4. Generate combined catalog.md with Mermaid graph
5. Report files updated

Output Format:

prompt-maintenance sync

Scanning sources...
✓ ana-service: 68 templates

Generated:
  ✓ apps/ana-service/prompts.json
  ✓ docs/prompts/ana-service.md
  ✓ docs/prompts/catalog.md

Done.

/prompt-maintenance check <file>

Validate single template (for hooks).

Process:

1. Parse template header
2. Validate structure (E001-E003)
3. Check encoding (E004)
4. Verify includes exist (E005)
5. Return pass/fail

Output Format (pass):

✓ lesson/exercise.jinja2 - Valid

Output Format (fail):

✗ lesson/exercise.jinja2
  E002: Missing Context field in header
  E005: Include not found: '_shared/missing.jinja2'

Parsing Logic

Header Extraction

def parse_header(content: str) -> dict:
    """Extract metadata from template header."""
    # Find header block
    match = re.search(r'\{#\s*=*\s*(.*?)\s*=*\s*#\}', content, re.DOTALL)
    if not match:
        return None

    header = match.group(1)

    # Extract fields
    result = {
        'path': None,
        'description': None,
        'context': [],
        'output': None,
    }

    # First line is path
    lines = header.strip().split('\n')
    if lines:
        result['path'] = lines[0].strip()

    # Find Context: { ... }
    context_match = re.search(r'Context:\s*\{\s*([^}]+)\s*\}', header)
    if context_match:
        vars = context_match.group(1)
        result['context'] = [v.strip() for v in vars.split(',')]

    # Find Output: ...
    output_match = re.search(r'Output:\s*(.+?)(?:\n|$)', header)
    if output_match:
        result['output'] = output_match.group(1).strip()

    # Description is everything between path and Context/Output
    # (simplified - extract middle lines)

    return result