---
name: update-guides
description: Validate recent changes (bug-free gate) then sync all documentation.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task
argument-hint: "[--full]"
---

# /update-guides — Validate + Sync Documentation

Two-phase skill: **validate first, document second.** Never codify broken code.

## Usage

```
/update-guides          # Validate session changes, then sync docs
/update-guides --full   # Validate ALL uncommitted changes (git diff), then sync docs
```

---

## PHASE 1: VALIDATE (Gate — must pass before Phase 2)

### Step 1.1: Detect What Changed

**Default mode (session context):**
- Use conversation context to identify files created/modified in this session
- List them explicitly for the user

**`--full` mode (git diff):**
- Run `git diff --name-only` and `git diff --cached --name-only` to find all uncommitted changes
- Also check `git status --porcelain` for untracked new files
- Combine into a single changed-files list

**Output:** Print the detected file list before proceeding.

```
CHANGED FILES DETECTED:
  lib/prompt_compiler.py        (new)
  lib/prompt_validators.py      (new)
  tools/generate_storyboard_keyframes.py  (modified)
  editors/serve.py              (modified)
  editors/shotlist_editor.html  (modified)
  ...
```

### Step 1.2: Validation Battery

Run ALL applicable checks against the changed files. Do not skip any category.

#### A. Python Syntax + Imports (all changed .py files)

For each `.py` file:
1. `python3 -c "import py_compile; py_compile.compile('FILE', doraise=True)"` — syntax check
2. Attempt to import the module (with sys.path set correctly) — catches missing dependencies, circular imports, undefined names
3. If the file has a `if __name__ == '__main__'` block, run `python3 FILE --help` (or equivalent) to verify CLI doesn't crash

#### B. Cross-File Consistency (imports, signatures, contracts)

For each changed `.py` file:
1. **Extract imports** — find every `from X import Y` and `import X`
2. **Verify targets exist** — confirm each imported name actually exists in the source module
3. **Check function signatures** — if file A calls `compile(shot, breakdown, episode, ...)` and file B defines `def compile(...)`, verify the argument names and required params match
4. **Check constant references** — if a file references `MODEL_CAPABILITIES["z_image"]`, verify that key exists in the source dict

For `.html`/`.js` files:
1. Verify API endpoints referenced in fetch() calls exist in serve.py
2. Check that onclick function names are defined in the same file's `<script>` block

For `.json` files:
1. Valid JSON (parse without error)
2. If it's a schema-controlled file (storyboard, breakdown, project_config), verify required keys exist

#### C. Functional Tests (actually run the code)

Based on what changed, run targeted functional checks:

| Changed File | Functional Test |
|---|---|
| `prompt_compiler.py` | Load a real storyboard + breakdown, compile a prompt, verify non-empty output with all 10 layers |
| `prompt_validators.py` | Run `validate_verb_strength()` on a compiled result, verify it returns dict or None |
| `generate_storyboard_keyframes.py` | Import check + verify `build_t2i_prompt()` returns a dict with `prompt`, `negative_prompt`, `prompt_hash` keys |
| `serve.py` | Syntax check + verify `_preview_prompt()` method exists and is callable |
| `shotlist_editor.html` | Verify JS function names referenced in onclick exist in the script block |
| `project_config.json` | Valid JSON + required keys (`camera_body`, `film_stock`, `hex_object_map`) |
| `verb_patterns.json` | Valid JSON + required keys (`micro_detail_patterns`, `bare_patterns`) |
| Any `tools/*.py` | `python3 FILE --help` if it has argparse |

For **any new module** (file that didn't exist before):
- Write a minimal test script that imports the module, calls its main public function with test data, and verifies the return type/shape
- Run the test script
- Delete the test script after

#### D. Existing Engine Validators (when relevant)

| Condition | Run |
|---|---|
| Breakdown-related changes | `python3 tools/validate_breakdown.py leviathan/` |
| Storyboard-related changes | `python3 tools/validate_storyboard.py leviathan/ --episode 1` |
| Doc/constants changes | `python3 tools/validate_docs.py` (or `/validate-docs` inline) |
| Visual bible changes | `python3 tools/validate_visual_bible.py leviathan/` |

### Step 1.3: Fix Loop

If ANY validation fails:

1. **Report the failure** clearly (file, check type, error message)
2. **Fix the issue** in the source code
3. **Re-run the failed check** to confirm the fix
4. **Repeat** until all checks pass
5. Maximum 3 fix attempts per issue — if still failing after 3, stop and report to user

### Step 1.4: Validation Report

```
═══════════════════════════════════════════════════════════════
PHASE 1: VALIDATION — PASSED
═══════════════════════════════════════════════════════════════

FILES VALIDATED: 8
  [PASS] lib/prompt_compiler.py
    - Syntax: OK
    - Imports: OK
    - Functional: compile() returns valid dict with 10 layers
  [PASS] lib/prompt_validators.py
    - Syntax: OK
    - Imports: OK
    - Functional: validate_verb_strength() runs correctly
  [PASS] tools/generate_storyboard_keyframes.py
    - Syntax: OK
    - Imports: OK
    - Cross-file: all prompt_compiler imports resolve
  ...

FIXES APPLIED: 1
  lib/prompt_compiler.py:804 — fixed missing default for negative_prompt

CROSS-FILE CHECKS: 5/5 passed
FUNCTIONAL TESTS: 4/4 passed

Proceeding to Phase 2...
═══════════════════════════════════════════════════════════════
```

If validation **fails** after fix loop exhausted:

```
═══════════════════════════════════════════════════════════════
PHASE 1: VALIDATION — FAILED (blocking Phase 2)
═══════════════════════════════════════════════════════════════

BLOCKING ISSUES:
  [FAIL] lib/prompt_compiler.py
    - Functional: compile() raises KeyError on episode 25
    - Fix attempts: 3/3 exhausted

Phase 2 (doc sync) SKIPPED — fix blocking issues first.
═══════════════════════════════════════════════════════════════
```

**Phase 2 DOES NOT RUN if Phase 1 fails.**

---

## PHASE 2: SYNC DOCUMENTATION

Only runs after Phase 1 passes. Updates all documentation to reflect the validated changes.

### Step 2.1: Identify What Needs Updating

Read each target doc and identify sections affected by the changed files.

**Source → Doc Mapping:**

| Source File | Updates |
|---|---|
| `CONSTANTS.md` | All docs referencing numeric values |
| `skills/format_v12/SKILL.md` | WORKFLOW_GUIDE (Format Rules), CLAUDE.md (V12 Constraints) |
| `skills/orchestration_process/SKILL.md` | WORKFLOW_GUIDE (Generation section) |
| `skills/dramatic_elements/SKILL.md` | WORKFLOW_GUIDE (Hooks/Cliffhangers) |
| `skills/relationship_earning/SKILL.md` | WORKFLOW_GUIDE (Relationship section) |
| `skills/treatment/SKILL.md` | WORKFLOW_GUIDE (Treatment Phase) |
| `SCRIPTING_REQUIREMENTS.md` | WORKFLOW_GUIDE (Development Phase) |
| `appendix_d_ai_video.md` | WORKFLOW_GUIDE (Visual Strategy) |
| `appendix_e_flux2_protocols.md` | WORKFLOW_GUIDE (Prompt Engineering) |
| `agents/*.md` | WORKFLOW_GUIDE (Command Reference) |
| `lenses/*.md` | WORKFLOW_GUIDE (Assessment Lenses) |
| `tools/*.py` | WORKFLOW_GUIDE (Python Scripts table), CLAUDE.md (Python Scripts table) |
| `lib/*.py` | WORKFLOW_GUIDE (Library modules), CLAUDE.md (if new public API) |
| `editors/*.py`, `*.html`, `*.js` | WORKFLOW_GUIDE (Visual Editors section) |
| `templates/*.json` | WORKFLOW_GUIDE (Templates section) |
| `.claude/skills/*/SKILL.md` | CLAUDE.md (Command Quick Reference, Skills Reference) |
| `[project]/ORCHESTRATION.md` | Only if project-specific constants changed |
| `[project]/visual/project_config.json` | WORKFLOW_GUIDE (Visual Production config) |

### Step 2.2: Update Target Documents

**Target documents (in update order):**

1. **`/docs/PRODUCTION_PIPELINE_GUIDE.md`** — Primary reference. Update affected sections.
2. **`/docs/PRODUCTION_PIPELINE_GUIDE.html`** — Regenerate from .md (or update inline if hand-maintained).
3. **`/CLAUDE.md`** — Quick Reference table, Command Reference table, Python Scripts table, Folder Structure.
4. **`/[project]/ORCHESTRATION.md`** — Only if project-specific rules changed.
5. **`/templates/`** — Update any template files that reference changed structures (e.g., `project_config_template.json`, `storyboard_schema.json`).

**Update rules:**
- Match the existing style and formatting of each target doc
- Preserve section structure — update content within sections, don't restructure
- Add new sections for genuinely new capabilities (e.g., new tool, new command)
- Remove references to deleted/deprecated features
- Keep CLAUDE.md tables sorted and consistent with WORKFLOW_GUIDE

### Step 2.3: Post-Sync Verification

After all docs are updated:

1. Run `python3 tools/validate_docs.py` (if it exists) to check numeric consistency
2. Grep all updated docs for common stale references:
   - Old function names that were renamed
   - Old file paths that were moved
   - Numeric values that don't match CONSTANTS.md
3. Verify no TODO/FIXME markers were introduced

### Step 2.4: Final Report

```
═══════════════════════════════════════════════════════════════
UPDATE-GUIDES: Complete
═══════════════════════════════════════════════════════════════

PHASE 1 — VALIDATION:
  Files validated: 8/8 passed
  Fixes applied: 1
  Functional tests: 4/4 passed

PHASE 2 — DOCUMENTATION SYNC:
  Source files checked: 12
  Docs updated:
    /docs/PRODUCTION_PIPELINE_GUIDE.md
      - Added "Prompt Compiler" section to Phase 6
      - Updated Python Scripts table (added prompt_compiler.py, prompt_validators.py)
      - Updated Visual Editors section (preview-prompt endpoint)
    /docs/PRODUCTION_PIPELINE_GUIDE.html
      - Regenerated from .md
    /CLAUDE.md
      - Updated Python Scripts table
      - Updated Folder Structure (lib/)
    /leviathan/ORCHESTRATION.md
      - No changes needed

  Post-sync verification: PASSED

═══════════════════════════════════════════════════════════════
```

---

## Related Skills

| Skill | Relationship |
|---|---|
| `/validate-docs` | Subset of Phase 1 — checks numeric/terminology only. `/update-guides` is the full pipeline. |
| `/engine-check` | Complementary — checks engine mechanics. `/update-guides` validates recent changes specifically. |