---
name: validate-docs
description: Verify all documentation is consistent with CONSTANTS.md and uses current terminology.
allowed-tools: Bash, Read, Glob
argument-hint: "[--verbose|--fix-refs]"
---

# /validate-docs - Documentation Consistency Checker

Verify all documentation is consistent with CONSTANTS.md and uses current terminology.

## Usage

```
/validate-docs
/validate-docs --verbose
/validate-docs --fix-refs
```

## Options

| Option | Description |
|--------|-------------|
| (none) | Check all docs, show only failures |
| `--verbose` | Show where canonical values appear (for auditing) |
| `--fix-refs` | Show which files need CONSTANTS.md references added |

## When to Use

Run this skill after:
- Changing any numeric value in `/CONSTANTS.md`
- Renaming terminology (e.g., "The Lens" to "Archetype-Worldview")
- Adding new constants or patterns
- Before committing documentation changes

## What It Checks

### Outdated Values
| Pattern | Replacement |
|---------|-------------|
| `250-315` | `450-500` (default) or see CONSTANTS.md |
| `280-350` | `450-500` (see CONSTANTS.md) |
| `265 words` | `450-500` (see CONSTANTS.md) |
| `350-400` | `450-500` (see CONSTANTS.md) |
| `330-420` | `450-500` (see CONSTANTS.md) |
| `The Lens` (without context) | `Archetype-Worldview` |

### Missing CONSTANTS.md References
Key documents that should reference CONSTANTS.md:
- `format_v12/SKILL.md`
- `treatment/SKILL.md`
- `relationship_earning/SKILL.md`
- `dramatic_elements/SKILL.md`
- `orchestration_process/SKILL.md`
- All appendices (a, b, c, d)
- `SCRIPTING_REQUIREMENTS.md`

### Terminology Issues
- "The Lens" should be "Archetype-Worldview" (except in lenses/ directory)

---

## Execution

When this skill is invoked:

```bash
python3 /tools/validate_docs.py [options]
```

### Exit Codes

| Code | Meaning |
|------|---------|
| `0` | PASS — All documents consistent |
| `1` | FAIL — Issues found, fix before proceeding |

---

## Example Output

### Clean (PASS)
```
======================================================================
DOCUMENTATION CONSISTENCY CHECK
Engine path: /Users/.../recoil
======================================================================

Scanning 59 markdown files...

======================================================================
SUMMARY
======================================================================
Files scanned: 59
Outdated values: 0
Terminology issues: 0
Missing CONSTANTS.md refs: 0

======================================================================
DOCUMENTATION CHECK: PASSED
All documents are consistent with CONSTANTS.md
======================================================================
```

### Issues Found (FAIL)
```
======================================================================
OUTDATED VALUES FOUND
======================================================================

  agents/revision_agent.md:378
    Found: 350-400
    Should be: 450-500 (see CONSTANTS.md)
    (old word count)

======================================================================
TERMINOLOGY ISSUES
======================================================================

  templates/STATUS_TEMPLATE.md:178
    Issue: "The Lens" should be "Archetype-Worldview"

======================================================================
DOCUMENTATION CHECK: ISSUES FOUND
Fix the issues above, then re-run this script.
======================================================================
```

---

## Workflow for Changing Values

```
1. Edit /CONSTANTS.md with new value

2. /validate-docs
   └── Identifies files with old values

3. Fix flagged files
   └── Update hardcoded values OR
   └── Add reference to CONSTANTS.md

4. /validate-docs
   └── Verify exit code 0

5. /update-guides (if needed)
   └── Sync guides with changes
```

---

## Adding New Patterns to Validator

To add detection for new values:

1. Edit `/tools/validate_docs.py`
2. Add to `CANONICAL_VALUES` dict:
   ```python
   'new_constant': {
       'pattern': r'regex_pattern',
       'value': 'canonical value',
       'category': 'category_name'
   }
   ```
3. Or add to `OUTDATED_VALUES` list:
   ```python
   {
       'pattern': r'old_value_regex',
       'replacement': 'new value (see CONSTANTS.md)',
       'description': 'what this was'
   }
   ```

---

## Related Skills

| Skill | Purpose |
|-------|---------|
| `/update-guides` | Sync guide content with engine changes |
| `/validate-docs` | Check numeric/terminology consistency |