prizmkit 1.1.111 → 1.1.113

package/bundled/skills/prizmkit-prizm-docs/SKILL.md

@@ -1,129 +1,150 @@
 ---
 name: "prizmkit-prizm-docs"
-description: "Project documentation specification and standard for AI-optimized progressive context loading. Defines the .prizmkit/prizm-docs/ 3-level hierarchy (L0/L1/L2), format rules, size limits, and loading protocol. Use this skill to: bootstrap docs for new projects (init), check doc freshness (status), regenerate stale modules (rebuild), validate format compliance (validate), or migrate existing docs (migrate). For incremental doc updates after code changes, use /prizmkit-retrospective instead — it is the sole writer of .prizmkit/prizm-docs/ during development. Trigger on: 'initialize docs', 'check doc status', 'rebuild docs', 'validate docs', 'migrate docs', 'docs are stale', 'prizm docs'. (project)"
+description: "Project documentation specification and management for AI-optimized progressive context loading. Defines the .prizmkit/prizm-docs/ L0/L1/L2 hierarchy, format rules, size limits, and loading protocol. Use this skill to bootstrap docs for new projects (init), check freshness (status), rebuild modules, validate format, migrate existing docs, or repair/resync docs after out-of-band drift such as manual edits, merges, or branch switches. For normal development updates after code changes, use /prizmkit-retrospective instead. Trigger on: 'initialize docs', 'check doc status', 'rebuild docs', 'validate docs', 'migrate docs', 'docs drifted', 'repair prizm docs'. (project)"
 ---
 
 # Prizm Docs - AI Documentation Framework
 
-Full specification: ${SKILL_DIR}/assets/prizm-docs-format.md
+Full specification: `${SKILL_DIR}/assets/prizm-docs-format.md`
 
 ## Intent Routing
 
-This skill handles 6 operations. When invoked, determine the user's intent and execute the matching operation:
+This skill handles documentation system operations. Determine the user's intent and execute the matching operation:
 
 | User Intent | Operation | Trigger Phrases |
 |---|---|---|
-| Bootstrap new project docs | **Init** | "initialize docs", "set up prizm docs", "bootstrap documentation" |
-| Sync docs after code changes | **Update** | "update docs", "sync documentation", "docs are stale" |
-| Check doc freshness | **Status** | "check docs", "are docs up to date", "doc status" |
-| Regenerate module docs | **Rebuild** | "rebuild docs for X", "regenerate module docs" |
-| Check format compliance | **Validate** | "validate docs", "check doc format", "docs valid?" |
-| Convert existing docs | **Migrate** | "migrate docs", "convert docs to prizm format" |
+| Bootstrap new project docs | Init | "initialize docs", "set up prizm docs", "bootstrap documentation" |
+| Repair docs after out-of-band drift | Update | "docs drifted", "repair prizm docs", "resync after merge", "docs stale after branch switch" |
+| Check doc freshness | Status | "check docs", "are docs up to date", "doc status" |
+| Regenerate module docs | Rebuild | "rebuild docs for X", "regenerate module docs" |
+| Check format compliance | Validate | "validate docs", "check doc format", "docs valid?" |
+| Convert existing docs | Migrate | "migrate docs", "convert docs to prizm format" |
 
----
+Do not route ordinary development-loop "update docs" or "sync docs" here. In normal feature/bugfix/refactor work, use `/prizmkit-retrospective`; it is the development docs writer.
 
 ## Role Clarification
 
-**This skill vs `/prizmkit-retrospective`**:
-
 | Aspect | `/prizmkit-prizm-docs` | `/prizmkit-retrospective` |
-|--------|----------------------|--------------------------|
-| **Role** | Documentation SPECIFICATION + BOOTSTRAP | Incremental WRITER during development |
-| **When** | Project setup, health checks, migrations | After feature completion, before commit |
-| **Writes** | Initial .prizmkit/prizm-docs/ structure (init, rebuild, migrate) | Incremental updates to existing .prizmkit/prizm-docs/ |
-| **Reads** | Source code structure (for init/rebuild) | git diff + code changes (for sync) |
-| **Knowledge** | Defines format rules, size limits, loading protocol | Extracts TRAPS/RULES/DECISIONS into `.prizmkit/prizm-docs/` |
+|--------|------------------------|---------------------------|
+| Role | Documentation specification, bootstrap, health checks, migration, out-of-band repair | Normal development writer |
+| When | Project setup, validation, rebuild, migration, docs drift after merges/manual edits | After implementation/review when code changes affect docs or durable knowledge |
+| Writes | Initial structure, rebuilds, migrations, repair/resync operations | Incremental task-scoped updates during development |
+| Reads | Source code structure and existing docs | Git diff, task artifacts, review/test results, changed source |
+| Knowledge | Defines format rules and loading protocol | Extracts durable TRAPS/RULES/DECISIONS |
 
-**Key principle**: `/prizmkit-prizm-docs` defines WHAT the docs should look like and bootstraps them. `/prizmkit-retrospective` is the SOLE WRITER that keeps docs in sync with code during ongoing development.
+Key principle: `/prizmkit-prizm-docs` defines and repairs the documentation system. `/prizmkit-retrospective` keeps docs in sync during ordinary development.
 
 ### When to Use
-- First-time project documentation setup (init)
-- Checking if docs are up to date (status)
-- Rebuilding stale module docs after major changes (rebuild)
-- Validating doc format compliance (validate)
-- Migrating existing docs to Prizm format (migrate)
-- User says "initialize docs", "check doc status", "rebuild docs", "validate docs"
+- First-time project documentation setup
+- Checking whether docs are fresh or valid
+- Rebuilding stale module docs after major structural changes
+- Migrating existing docs to Prizm format
+- Repairing docs that drifted because of manual edits, merges, branch switches, or changes made outside the normal dev loop
 
 ### When NOT to Use
-- Incremental doc updates after code changes → use /prizmkit-retrospective (the sole writer during development)
-- Project has no .prizmkit/prizm-docs/ and user doesn't want to initialize
-- User wants to edit code → use /prizmkit-plan and /prizmkit-implement
+- Incremental doc updates after normal code changes → use `/prizmkit-retrospective`
+- User wants to edit code → use `/prizmkit-plan` and `/prizmkit-implement`
+- Project has no `.prizmkit/prizm-docs/` and the user does not want to initialize docs
 
 ## Operation: Init
 
-Bootstrap .prizmkit/prizm-docs/ for the current project.
-PRECONDITION: No .prizmkit/prizm-docs/ directory exists, or user confirms overwrite.
-→ Read `${SKILL_DIR}/references/op-init.md` for detailed steps.
+Bootstrap `.prizmkit/prizm-docs/` for the current project.
+
+Precondition: no `.prizmkit/prizm-docs/` directory exists, or user confirms overwrite.
+
+Read `${SKILL_DIR}/references/op-init.md` for detailed steps.
 
 ## Operation: Update
 
-Update .prizmkit/prizm-docs/ to reflect recent code changes.
-PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
-**Scope guard**: Use Update only for out-of-band resync — when docs drifted from code after manual edits, merges, branch switches, or other changes made outside the dev loop. During the normal feature/bugfix/refactor loop, do NOT use Update: `/prizmkit-retrospective` is the sole writer and keeps docs in sync per task. Running both is redundant and risks conflicting edits.
-→ Read `${SKILL_DIR}/references/op-update.md` for detailed steps.
+Repair or resync `.prizmkit/prizm-docs/` after out-of-band drift.
+
+Precondition: `.prizmkit/prizm-docs/` exists with `root.prizm`.
+
+Use Update only when docs drifted outside the normal development loop, such as:
+
+- manual code edits without retrospective
+- merges or rebases
+- branch switches
+- generated code movement
+- user explicitly asks to repair stale Prizm docs
+
+During normal feature/bugfix/refactor work, do not use Update; use `/prizmkit-retrospective` to avoid duplicate writers and conflicting edits.
+
+Read `${SKILL_DIR}/references/op-update.md` for detailed steps.
 
 ## Operation: Status
 
-Check freshness of all .prizm docs.
-PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
-→ Read `${SKILL_DIR}/references/op-status.md` for detailed steps.
+Check freshness of all `.prizm` docs.
+
+Precondition: `.prizmkit/prizm-docs/` exists with `root.prizm`.
+
+Read `${SKILL_DIR}/references/op-status.md` for detailed steps.
 
 ## Operation: Rebuild
 
-Regenerate docs for a specific module from scratch. Requires a module path argument.
-PRECONDITION: .prizmkit/prizm-docs/ exists. Module path is valid.
-→ Read `${SKILL_DIR}/references/op-rebuild.md` for detailed steps.
+Regenerate docs for a specific module from scratch.
+
+Precondition: `.prizmkit/prizm-docs/` exists and module path is valid.
+
+Read `${SKILL_DIR}/references/op-rebuild.md` for detailed steps.
 
 ## Operation: Validate
 
-Check format compliance and consistency of all .prizm docs.
-PRECONDITION: .prizmkit/prizm-docs/ exists.
-→ Read `${SKILL_DIR}/references/op-validate.md` for detailed steps.
+Check format compliance and consistency of all `.prizm` docs.
+
+Precondition: `.prizmkit/prizm-docs/` exists.
+
+Read `${SKILL_DIR}/references/op-validate.md` for detailed steps.
 
 ## Operation: Migrate
 
-Convert existing documentation to .prizmkit/prizm-docs/ format.
-PRECONDITION: Existing docs/ or docs/AI_CONTEXT/ directory. No .prizmkit/prizm-docs/ (or user confirms overwrite).
+Convert existing documentation to `.prizmkit/prizm-docs/` format.
 
-STEPS:
-1. DISCOVER existing docs: Scan docs/, docs/AI_CONTEXT/, README.md, ARCHITECTURE.md, and any structured documentation files.
-2. EXTRACT information from existing docs: project metadata, module descriptions, architecture patterns, rules, decisions, dependencies.
-3. MAP existing doc content to Prizm levels: project-wide info -> L0 root.prizm, module-level info -> L1 docs (MODULE, FILES, RESPONSIBILITY, KEY_FILES, DEPENDENCIES), detailed module info -> L2 docs (INTERFACES, DATA_FLOW, TRAPS, DECISIONS, domain-specific sections).
-4. CONVERT prose content to KEY: value format. Strip markdown formatting, tables, diagrams. Condense explanatory text into single-line values.
-5. GENERATE .prizmkit/prizm-docs/ structure following standard init procedure but seeded with extracted information instead of scanning source code alone.
-6. VALIDATE migrated docs against Prizm format rules and size limits.
-7. REPORT migration summary: files processed, content mapped, information that could not be automatically converted (requires manual review).
+Precondition: existing `docs/`, `docs/AI_CONTEXT/`, README, or architecture docs; no `.prizmkit/prizm-docs/` unless user confirms overwrite.
 
-OUTPUT: Migration report with list of source docs processed, generated .prizm files, and any manual review items.
+Steps:
+1. Discover existing docs: `docs/`, `docs/AI_CONTEXT/`, `README.md`, `ARCHITECTURE.md`, and structured documentation files.
+2. Extract project metadata, module descriptions, architecture patterns, rules, decisions, and dependencies.
+3. Map project-wide info to L0, module structure to L1, and behavioral details to L2.
+4. Convert prose to KEY: value format and strip markdown tables, diagrams, and decorative formatting.
+5. Generate `.prizmkit/prizm-docs/` using init structure seeded with extracted information.
+6. Validate migrated docs against format rules and size limits.
+7. Report files processed, generated `.prizm` files, and manual review items.
 
 ## Error Handling
 
-- **root.prizm is corrupted or invalid format**: Back up the existing file, then run Rebuild on all modules to regenerate from source code.
-- **Broken pointers (-> references to non-existent files)**: Create the missing .prizm file if the source module exists; remove the pointer if the source module was deleted.
-- **Size limit exceeded**: For L0, consolidate MODULE_INDEX entries. For L1, move implementation details to L2. For L2, trim non-essential derived detail and keep only durable project knowledge.
-- **No git history available**: Fall back to filesystem timestamps for freshness checks; warn user that accuracy may be reduced.
+- `root.prizm` corrupted or invalid: back it up, then rebuild affected docs from source.
+- Broken pointers: create the missing `.prizm` file if the source module exists; remove the pointer if the source module was deleted.
+- Size limit exceeded: consolidate L0, move L1 implementation detail to L2, trim L2 derived detail.
+- No git history: fall back to filesystem timestamps for freshness checks and warn that accuracy is reduced.
+
+## Key Protocols
+
+For detailed protocol specifications, read `assets/prizm-docs-format.md`:
 
-### Key Protocols (reference)
-For detailed protocol specifications, see prizm-docs-format.md:
 - Progressive Loading: Section 6.1
-- Auto-Update: Section 7.1
+- Update/repair protocol: Section 7
 - RULES hierarchy: Section 3.1
 
 ## Examples
 
-**Init output (Node.js project):**
-```
+**Init output:**
+
+```text
 Generated .prizmkit/prizm-docs/:
   root.prizm (L0) — 3 modules in MODULE_INDEX
-  routes.prizm (L1) — 12 files, 4 interfaces
-  models.prizm (L1) — 8 files, 3 interfaces
-  services.prizm (L1) — 15 files, 6 interfaces
+  routes.prizm (L1) — module structure and dependencies
+  models.prizm (L1) — module structure and dependencies
+  services.prizm (L1) — module structure and dependencies
 ```
 
-**Update after adding new API endpoint:**
-```
-Changed: src/routes/avatar.ts (A), src/models/user.ts (M)
-Updated: .prizmkit/prizm-docs/routes.prizm — added avatar.ts to KEY_FILES, new POST /api/avatar interface
-Updated: .prizmkit/prizm-docs/models.prizm — updated User interface with avatar_url field
-Skipped: .prizmkit/prizm-docs/services.prizm — no changes in services module
+L1 docs are structural indexes. Interface signatures, data flow, TRAPS, and DECISIONS belong in L2 docs.
+
+**Out-of-band repair after merge:**
+
+```text
+Changed outside normal dev loop: src/routes/avatar.ts (A), src/models/user.ts (M)
+Updated: .prizmkit/prizm-docs/routes.prizm — added avatar route file mapping
+Created: .prizmkit/prizm-docs/routes/avatar.prizm — recorded new route interfaces and traps
+Updated: .prizmkit/prizm-docs/models.prizm — file count changed
 ```

package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md

@@ -29,7 +29,7 @@ LICENSE: MIT
 
 WHAT: Prizm is a self-maintaining documentation system where AI reads, generates, updates, and loads project context progressively.
 WHY: Reduce AI hallucinations, minimize token waste, ensure AI has accurate project knowledge at all times.
-HOW: Three-level progressive loading (L0 -> L1 -> L2) with auto-update before every commit.
+HOW: Three-level progressive loading (L0 -> L1 -> L2) with conditional retrospective before commits when code changes affect structure, interfaces, dependencies, behavior, or durable project knowledge.
 
 CORE_PRINCIPLES:
 - Token efficiency over human readability
@@ -350,7 +350,7 @@ FOR any source file at path P:
   1. Walk up directory tree to find the first ancestor D where .prizmkit/prizm-docs/<D>.prizm exists
   2. That file is the L1 doc for this source file
   3. If P is inside a subdirectory S of D, check if .prizmkit/prizm-docs/<D>/<S>.prizm exists for L2
-  4. If no .prizm doc found, the module is undocumented (may need prizmkit-prizm-docs Update operation)
+  4. If no .prizm doc found, the module is undocumented (may need retrospective after development or prizmkit-prizm-docs Update for out-of-band repair)
 
 ---
 
@@ -418,12 +418,12 @@ EXAMPLES:
 
 ## 7.1 Trigger
 
-WHEN: Before every commit (detected automatically via hook, or manually via prizmkit-prizm-docs Update operation)
-GOAL: Keep prizm docs synchronized with source code
+WHEN: During normal development, run `/prizmkit-retrospective` before commits when structure, interfaces, dependencies, behavior, or durable project knowledge changed. Use `prizmkit-prizm-docs Update` only for out-of-band repair/resync after docs drifted outside the normal development loop.
+GOAL: Keep prizm docs synchronized with source code without creating multiple competing docs writers.
 
 ## 7.2 Update Decision Logic
 
-SUMMARY: Get changed files → map to modules → classify (A/D/M/R) → update docs bottom-up (L2→L1→L0) → skip if no structural impact → enforce size limits → stage.
+SUMMARY: For normal development, `/prizmkit-retrospective` gets changed files → maps modules → classifies (A/D/M/R) → updates docs bottom-up (L2→L1→L0) → skips if no structural or durable-knowledge impact → enforces size limits → stages. For out-of-band drift, `prizmkit-prizm-docs Update` runs the same repair shape after confirming the drift source.
 
 DETAILED_STEPS: → ${SKILL_DIR}/references/op-update.md
 
@@ -491,20 +491,22 @@ EXCLUDE: .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bi
 
 ## 9.2 Post-Init Behavior
 
-After initialization, L2 docs are created incrementally:
+After initialization, L2 docs are created incrementally by retrospective when changed source files provide meaningful behavior or durable knowledge:
 
 ON_MODIFY trigger:
-- First time AI modifies a file in sub-module S within module M:
-  IF .prizmkit/prizm-docs/<M>/<S>.prizm does not exist:
-    AI reads the source files in S, generates L2 doc, then proceeds with modification
-- This ensures L2 docs have real depth, written when AI has actual context
+- Before editing a file in sub-module S within module M:
+  IF .prizmkit/prizm-docs/<M>/<S>.prizm exists:
+    AI reads the relevant L2 sections.
+  ELSE:
+    AI reads the target source files as fallback and proceeds with the modification.
+- After the change, `/prizmkit-retrospective` creates L2 if the changed files contain meaningful interfaces, data flow, traps, or decisions worth preserving.
+- This keeps initialization lightweight while still capturing L2 depth when real change context exists.
 
 ON_DEEP_READ trigger:
 - When AI needs to deeply understand a module but not modify it (e.g., code review, architecture analysis, dependency tracing, explaining complex logic):
   IF .prizmkit/prizm-docs/<M>/<S>.prizm does not exist:
-    AI reads the source files in S, generates L2 doc for future reference
-- This ensures L2 docs are available for read-heavy analysis tasks, not just modifications
-- RATIONALE: Some tasks require deep understanding without editing (reviewing PRs, answering architecture questions, tracing bugs). Generating L2 during these tasks captures valuable context.
+    AI reads the relevant source files for the current task and may recommend a retrospective or repair pass if durable L2 knowledge should be preserved.
+- Do not create placeholder L2 docs just because a module was read; create L2 only when there is meaningful behavior, interfaces, traps, or decisions to record.
 
 ---
 
@@ -517,7 +519,7 @@ The Prizm skill is defined at: ${SKILL_DIR}/SKILL.md
 OPERATIONS (all invoked via the prizmkit-prizm-docs skill):
 
   Init       - Bootstrap .prizmkit/prizm-docs/ for a new project. → ${SKILL_DIR}/references/op-init.md
-  Update     - Sync docs with code changes. → ${SKILL_DIR}/references/op-update.md
+  Update     - Repair/resync docs after out-of-band drift. → ${SKILL_DIR}/references/op-update.md
   Status     - Check freshness of all docs. → ${SKILL_DIR}/references/op-status.md
   Rebuild    - Regenerate docs for a specific module. → ${SKILL_DIR}/references/op-rebuild.md
   Validate   - Check format compliance and consistency. → ${SKILL_DIR}/references/op-validate.md
@@ -548,7 +550,7 @@ JSON:
         "hooks": [
           {
             "type": "command",
-            "command": "echo 'PRIZMKIT_MAINTENANCE_REQUIRED: Before committing, you MUST run /prizmkit-retrospective. It maintains .prizmkit/prizm-docs/ architecture index — structural sync (KEY_FILES, INTERFACES, DEPENDENCIES) + TRAPS/RULES/DECISIONS injection. After retrospective completes, proceed with /prizmkit-committer for the actual git commit.'"
+            "command": "echo 'PRIZMKIT_MAINTENANCE_CHECK: Before committing, check whether /prizmkit-retrospective applies. Run it when this change affects structure, interfaces, dependencies, behavior, or durable TRAPS/RULES/DECISIONS. Skip it for direct edits with no docs impact. Then proceed with /prizmkit-committer for the actual git commit.'"
           }
         ]
       }
@@ -571,12 +573,12 @@ KEYWORDS_DETECTED: commit, push, finish, done, ship, merge, PR, pull request, /c
 
 The hook configuration above is specific to CodeBuddy Code.
 For other AI coding assistants:
-- Cursor: Use .cursorrules file to add the auto-update protocol as a rule
+- Cursor: Use .cursorrules file to add the conditional retrospective protocol as a rule
 - Aider: Use .aider.conf.yml conventions section
 - Continue: Use .continue/config.json customInstructions
-- Generic: Add the auto-update protocol text to whatever system prompt or rules file the tool supports
+- Generic: Add the conditional retrospective protocol text to whatever system prompt or rules file the tool supports
 
-The core requirement is: before any commit operation, AI must update affected .prizmkit/prizm-docs/ files.
+The core requirement is: before commit, AI must check whether affected `.prizmkit/prizm-docs/` files need retrospective updates. Run `/prizmkit-retrospective` when the change affects structure, interfaces, dependencies, behavior, or durable TRAPS/RULES/DECISIONS; skip it for direct edits with no docs impact.
 
 ---
 

package/bundled/skills/prizmkit-prizm-docs/references/op-init.md

@@ -21,8 +21,8 @@ STEPS:
    - Top-level module M → write .prizmkit/prizm-docs/<M>.prizm (include SUBDIRS section with pointers to sub-module docs)
    - Sub-module S inside M → write .prizmkit/prizm-docs/<M>/<S>.prizm
    Each L1 includes MODULE (full relative path), FILES count, RESPONSIBILITY, SUBDIRS with pointers, KEY_FILES (5-10 most important), DEPENDENCIES (imports, imported-by, external), RULES (1-3 most critical only). L1 does NOT include INTERFACES, DATA_FLOW, TRAPS, or DECISIONS (those are L2, generated lazily). Max 4KB each.
-6. Skip L2 docs during init — L2 is created lazily on first file modification or when AI needs deep understanding (ON_DEEP_READ trigger). L2 contains behavioral detail: INTERFACES, DATA_FLOW, TRAPS, DECISIONS, full RULES, domain-specific sections.
-7. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/prizm-docs-format.md.md Section 11.
+6. Skip L2 docs during init — L2 docs are created after real context exists, not as placeholders. During implementation, if relevant L2 is missing, the implementing skill reads target source files as fallback and proceeds. `/prizmkit-retrospective` creates or updates L2 after the change only when durable structure, behavior, dependencies, interfaces, or TRAPS exist. Explicit `/prizmkit-prizm-docs` repair/rebuild may also create L2 when fixing out-of-band doc drift.
+7. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/prizm-docs-format.md Section 11.
 8. Validate all generated docs: size limits (L0 <= 4KB, L1 <= 4KB), pointer resolution (every -> reference resolves), no circular dependencies, KEY: value format compliance, no anti-patterns (prose, code blocks, markdown headers), L1 does not contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS, no CHANGELOG sections/files, no UPDATED/date metadata, no feature/bug/refactor/task/session/run/pipeline/workflow IDs, no branch names, no absolute worktree paths, and no `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
 9. Report summary: modules discovered, L1 docs generated, files excluded, warnings.
 
@@ -30,16 +30,14 @@ OUTPUT: List of generated files, module count, and validation results.
 
 ## Post-Init Behavior
 
-After initialization, L2 docs are created incrementally:
+After initialization, L2 docs are created only when durable context exists:
 
-ON_MODIFY trigger:
-- First time AI modifies a file in sub-module S within module M:
-  IF .prizmkit/prizm-docs/<M>/<S>.prizm does not exist:
-    AI reads the source files in S, generates L2 doc, then proceeds with modification
-- This ensures L2 docs have real depth, written when AI has actual context
+ON_MODIFY behavior:
+- When an AI modifies a file in sub-module S within module M and `.prizmkit/prizm-docs/<M>/<S>.prizm` does not exist, the implementation reads the source files in S as fallback context and proceeds.
+- Do not block implementation only to create a placeholder L2 doc.
+- After the change, run `/prizmkit-retrospective` when structure, interfaces, dependencies, behavior, or durable TRAPS changed; retrospective creates or updates L2 then.
 
-ON_DEEP_READ trigger:
-- When AI needs to deeply understand a module but not modify it (e.g., code review, architecture analysis, dependency tracing, explaining complex logic):
-  IF .prizmkit/prizm-docs/<M>/<S>.prizm does not exist:
-    AI reads the source files in S, generates L2 doc for future reference
-- This ensures L2 docs are available for read-heavy analysis tasks, not just modifications
+ON_DEEP_READ behavior:
+- When an AI needs deep understanding but L2 is absent, read the relevant source files directly as fallback context.
+- Create L2 through `/prizmkit-retrospective` after normal development work, or through explicit `/prizmkit-prizm-docs` repair/rebuild when fixing out-of-band doc drift.
+- Do not create L2 merely because a module was read; L2 should capture durable knowledge, not transient investigation notes.

package/bundled/skills/prizmkit-prizm-docs/references/op-update.md

@@ -1,19 +1,23 @@
-# Operation: Update — Detailed Steps
+# Operation: Update — Out-of-Band Repair/Resync
 
-Update .prizmkit/prizm-docs/ to reflect recent code changes.
+Repair `.prizmkit/prizm-docs/` after docs drifted outside the normal development loop.
 
-PRECONDITION: .prizmkit/prizm-docs/ exists with root.prizm.
+PRECONDITION: `.prizmkit/prizm-docs/` exists with `root.prizm`.
+
+Use this operation for manual edits, merges, rebases, branch switches, generated code movement, or other changes that did not pass through `/prizmkit-retrospective`. During ordinary feature/bugfix/refactor work, use `/prizmkit-retrospective` instead.
 
 STEPS:
-1. Get changed files via `git diff --cached --name-status`. If nothing staged, use `git diff --name-status`. If no git changes at all, do full rescan comparing code against existing docs — this includes checking for modules that have source files but no L2 doc.
-2. Map changed files to modules by matching against MODULE_INDEX or MODULE_GROUPS in root.prizm. Group changes by module.
-3. Classify each change: A (added) -> new KEY_FILES entries. D (deleted) -> remove entries, update counts. M (modified) -> check dependency changes. R (renamed) -> update all path references.
-4. Update affected docs: L2 first (KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, TRAPS, DECISIONS), then L1 (FILES count, KEY_FILES, DEPENDENCIES — L1 does NOT contain INTERFACES/DATA_FLOW/TRAPS/DECISIONS), then L0 (MODULE_INDEX or MODULE_GROUPS counts, CROSS_CUTTING) only if structural change. Do not write CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths — git tracks history. **Preserve** any `PROJECT_BRIEF:` line in root.prizm — it is managed by prizmkit-init, not by this skill.
-5. Skip updates if: only internal implementation changed (no interface/dependency change), only comments/whitespace/formatting, only .prizm files changed. DO NOT skip test file changes or bug fixes — they may reveal TRAPS worth capturing in L2.
-6. If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA) and matches no existing module: create L1 immediately, add to MODULE_INDEX. If the current diff includes Added or Modified source files in this module → also create L2 immediately with sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS. Otherwise defer L2.
-6a. **L2 gap check** (runs during full rescan mode only — when no git changes detected): For each existing module in MODULE_INDEX, check if L2 doc exists. If L2 is missing and the module has source files with meaningful logic (not trivial config/wrapper) → create L2 with sections: MODULE, FILES, RESPONSIBILITY, INTERFACES, DATA_FLOW, KEY_FILES, DEPENDENCIES, RULES, TRAPS, DECISIONS. This ensures Update fills documentation gaps left by previous sessions.
-7. Enforce size limits: L0 > 4KB -> consolidate. L1 > 4KB -> trim KEY_FILES descriptions, ensure RULES <= 3 entries. L2 > 5KB -> trim non-essential derived detail or split oversized cross-cutting detail.
-7a. Validate memory hygiene: no CHANGELOG/UPDATED fields, no workflow metadata, no L1 behavioral sections.
-8. Stage updated .prizm files via `git add .prizmkit/prizm-docs/`
+1. Identify drift source. Prefer explicit user context; otherwise inspect git changes with `git diff --cached --name-status`, then `git diff --name-status`. If no git changes exist, run a bounded rescan comparing code structure against existing docs.
+2. Map changed files to modules by matching MODULE_INDEX or MODULE_GROUPS in `root.prizm`.
+3. Classify each change: A (added) -> new KEY_FILES entries; D (deleted) -> remove entries and update counts; M (modified) -> check dependency/interface/data-flow impact; R (renamed) -> update path references.
+4. Update affected docs bottom-up: L2 first for INTERFACES/DATA_FLOW/DEPENDENCIES/TRAPS/DECISIONS, then L1 for FILES/KEY_FILES/SUBDIRS/DEPENDENCIES, then L0 only for structural module changes. L1 does not contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS.
+5. Preserve `PROJECT_BRIEF:` in `root.prizm`; it is managed by `/prizmkit-init`.
+6. Do not write CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths.
+7. Skip updates for comments/whitespace/formatting-only changes, `.prizm`-only changes, and test-only changes that reveal no durable boundaries, traps, interface constraints, behavior rules, or regression knowledge.
+8. If a new directory qualifies as a module and matches no existing module, create L1 immediately and add it to MODULE_INDEX or MODULE_GROUPS. Create L2 only when source files contain meaningful behavior worth documenting.
+9. During full rescan mode, check for missing L2 docs only for modules with meaningful source behavior. Create L2 docs when the missing detail would help future AI work; do not create empty placeholder L2 files.
+10. Enforce size limits: L0 <= 4KB, L1 <= 4KB, L2 <= 5KB.
+11. Validate memory hygiene and format compliance.
+12. Stage updated `.prizm` files with `git add .prizmkit/prizm-docs/` only after reviewing the repair summary.
 
-OUTPUT: List of updated/created/skipped docs with reasons.
+OUTPUT: List updated, created, removed, and skipped docs with reasons. Explicitly state that this was an out-of-band repair/resync, not a normal development retrospective.

package/bundled/skills/prizmkit-retrospective/SKILL.md

@@ -1,87 +1,95 @@
 ---
 name: "prizmkit-retrospective"
-description: "Incremental .prizmkit/prizm-docs/ maintainer. Performs two jobs: (1) structural sync — update .prizmkit/prizm-docs/ KEY_FILES/INTERFACES/DEPENDENCIES, (2) architecture knowledge — inject TRAPS/RULES/DECISIONS into .prizmkit/prizm-docs/. All project knowledge lives in .prizmkit/prizm-docs/ . Run after code review passes and before committing. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
+description: "Incremental .prizmkit/prizm-docs/ maintainer and normal development docs writer. Performs structural sync for changed modules and injects durable TRAPS/RULES/DECISIONS when feature, bugfix, refactor, or test work creates lasting project knowledge. Run after code review or implementation when the chosen lifecycle path changed structure, interfaces, dependencies, behavior, or durable knowledge, and before committing those changes. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
 ---
 
 # PrizmKit Retrospective
 
-| Store | Location | Content | Purpose |
-|-------|----------|---------|---------|
-| **Architecture Index** | `.prizmkit/prizm-docs/` | MODULE, FILES, INTERFACES, DEPENDENCIES, TRAPS, RULES, DECISIONS | AI quickly locates code structure, interfaces, known pitfalls, and key design decisions |
+`/prizmkit-retrospective` is the normal development writer for `.prizmkit/prizm-docs/`.
 
-**This skill handles both structural sync and knowledge injection in one pass:**
+It performs two jobs:
 
-1. **Structural Sync** — reflect what changed in code → `.prizmkit/prizm-docs/` (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
-2. **Architecture Knowledge** — inject TRAPS, RULES, and DECISIONS → `.prizmkit/prizm-docs/`
+1. **Structural Sync** — reflect changed code structure, interfaces, dependencies, and file mappings in `.prizmkit/prizm-docs/`.
+2. **Knowledge Injection** — add durable TRAPS, RULES, and DECISIONS discovered during the task.
 
-For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` instead.
+For first-time documentation setup, validation, rebuild, migration, or out-of-band repair after docs drift, use `/prizmkit-prizm-docs` instead.
 
 ## When to Use
 
-- **Before every commit** (mandatory in pipeline) — ensures docs and code are in sync
-- After completing a feature, refactoring, or bug fix
-- After code review passes
-- User says "retrospective", "retro", "update docs", "sync docs", "wrap up"
+- Full path: after code review passes and before commit when code/docs knowledge changed.
+- Fast path: before commit only when structure, interfaces, dependencies, behavior, or durable project knowledge changed.
+- Bug fixes: run structural sync when the fix changes interfaces/dependencies/observable behavior; run knowledge injection only when the fix reveals durable TRAPS/RULES/DECISIONS.
+- Test-only changes: run only when tests reveal durable boundaries, traps, interface constraints, behavior rules, or regression knowledge worth preserving.
+- User says "retrospective", "retro", "update docs", "sync docs", or "wrap up" during normal development.
+
+## When NOT to Use
+
+- Direct edit with no structural, behavioral, dependency, interface, or durable-knowledge change.
+- Only comments, whitespace, or formatting changed.
+- Only `.prizm` files changed — avoid circular updates.
+- Test-only changes that merely add coverage for already documented behavior and reveal no new durable knowledge.
+- Out-of-band doc repair/resync after merges or branch switches — use `/prizmkit-prizm-docs` Update/Rebuild/Validate.
 
 ## Input
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `artifact_dir` | No | Directory containing spec.md, plan.md, review-report.md. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md`. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. If no artifact directory found, run in standalone mode (structural sync only from `git diff`). |
+| `artifact_dir` | No | Directory containing `spec.md`, `plan.md`, and optionally `review-report.md`. If omitted, scan `.prizmkit/` subdirectories for the most recently modified directory with a `plan.md`. When invoked as a handoff step, reuse the caller's `artifact_dir` rather than re-detecting. If no artifact directory is found, run standalone structural sync from `git diff`. |
 
-## When NOT to Use
+## Job 1: Structural Sync
 
-- Only comments, whitespace, or formatting changed — no structural/knowledge change
-- Only test files changed — no module-level impact
-- Only .prizm files changed — avoid circular updates
+Synchronize `.prizmkit/prizm-docs/` structure with actual codebase changes from this session.
 
----
+Read `${SKILL_DIR}/references/structural-sync-steps.md` for the detailed procedure.
 
-### Job 1: Structural Sync (always runs)
-Synchronize `.prizmkit/prizm-docs/` structure with actual codebase changes from this session.
-→ Read `${SKILL_DIR}/references/structural-sync-steps.md` for the detailed procedure.
+Key outputs:
+- L1 file counts and module mappings
+- L2 KEY_FILES / INTERFACES / DATA_FLOW / DEPENDENCIES for affected diff files
+- New L1/L2 docs when newly changed source directories require them
+- Stale TRAPS cleanup when needed
 
-**Key outputs**: Synced L1 file counts, L2 INTERFACES/DATA_FLOW, DEPENDENCIES, and stale TRAPS cleanup.
+Memory hygiene: `.prizmkit/prizm-docs/` must not contain CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths. Convert artifact-scoped wording into durable product/domain language before writing.
 
-**Memory hygiene**: `.prizmkit/prizm-docs/` must not contain CHANGELOG sections/files, UPDATED/date metadata, feature/bug/refactor/task/session/run/pipeline/workflow IDs, branch names, absolute worktree paths, or `.prizmkit/specs` / `.prizmkit/dev-pipeline` artifact paths. Convert artifact-scoped wording into durable product/domain language before writing.
+## Job 2: Knowledge Injection
 
----
+Inject newly discovered durable project knowledge into architecture docs.
 
-### Job 2: Knowledge Injection (conditional)
-Inject newly discovered project knowledge (TRAPS, RULES, DECISIONS) into architecture docs.
-→ Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for the detailed procedure.
+Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for the detailed procedure.
 
-**Review gate**: Before running Job 2, check `review-report.md` in the artifact directory for the `## Verdict:` line:
-- Verdict is `PASS` → proceed
-- Verdict is `NEEDS_FIXES` → **skip Job 2** — do not inject knowledge for code that hasn't passed review. Output warning: "Review report has unresolved findings. Skipping knowledge injection."
-- No `review-report.md` found → proceed with warning
-- No artifact directory (standalone mode) → skip Job 2, only Job 1 runs
+### Review Gate
 
-**Skip for**: pure refactors (no behavioral change).
+Before Job 2, check `review-report.md` in the artifact directory when present:
 
-**Bug Fix Documentation Policy**:
-- DEFAULT for bug fixes: Run Job 1 (structural sync) only. Skip Job 2 (knowledge injection).
-- RUN Job 2 when the bug fix causes any of:
-  • Interface signature changes
-  • Dependency additions/removals
-  • Observable behavior changes to existing features
-  • Newly discovered TRAPs (gotchas/pitfalls)
-- When any of the above apply, run full retrospective (Job 1 + Job 2).
+- Verdict `PASS` → proceed.
+- Verdict `NEEDS_FIXES` → skip Job 2 and warn: "Review report has unresolved findings. Skipping knowledge injection."
+- No `review-report.md` → proceed with warning for Fast path or standalone mode.
+- No artifact directory → skip Job 2 unless the user explicitly provides durable knowledge to record.
 
-**Key outputs**: New TRAPS entries, RULES updates, DECISIONS records in relevant L1/L2 docs and root.prizm.
+### Knowledge Injection Triggers
 
----
+Run Job 2 when the task produced durable knowledge such as:
+
+- New TRAPS, gotchas, race conditions, or surprising coupling
+- New architectural rules or decisions
+- Interface signature or contract changes
+- Dependency additions/removals that affect module behavior
+- Observable behavior changes to existing features
+- Test-only discoveries that document new boundary conditions, regression rules, or interface constraints
+
+Skip Job 2 for pure refactors with no durable design or behavior knowledge.
+
+## Final: Stage Docs
 
-## Final: Stage
+Stage doc changes only after verifying they are intended:
 
-**3a.** Stage all doc changes:
 ```bash
 git add .prizmkit/prizm-docs/
 ```
 
-**HANDOFF:** `/prizmkit-committer`
+Do not stage unrelated files.
 
 ## Output
 
-- `.prizmkit/prizm-docs/*.prizm` — Structurally synced + TRAPS/RULES/DECISIONS enriched
-- All `.prizmkit/prizm-docs/` changes staged via `git add`
+- Updated `.prizmkit/prizm-docs/*.prizm` files when sync or knowledge injection applies
+- Summary of updated, created, and skipped docs with reasons
+- Handoff: `/prizmkit-committer`