prizmkit 1.1.8 → 1.1.10

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

@@ -5,7 +5,7 @@ description: "Project documentation specification and standard for AI-optimized
 
 # Prizm Docs - AI Documentation Framework
 
-Full specification: ${SKILL_DIR}/assets/PRIZM-SPEC.md
+Full specification: ${SKILL_DIR}/assets/prizm-docs-format.md
 
 ## Intent Routing
 
@@ -39,113 +39,42 @@ This skill handles 6 operations. When invoked, determine the user's intent and e
 ## Operation: Init
 
 Bootstrap .prizm-docs/ for the current project.
-
 PRECONDITION: No .prizm-docs/ directory exists, or user confirms overwrite.
-
-STEPS:
-1. Detect project type by scanning for build system files (go.mod, package.json, requirements.txt, Cargo.toml, pom.xml, *.csproj). Identify primary language, framework, build command, test command, and entry points.
-2. Discover modules using semantic MODULE_DISCOVERY_CRITERIA (see PRIZM-SPEC Section 9.1 Step 2):
-   - A directory qualifies as a module if it contains source files forming a logical unit, contains entry/config/interface files, contains qualifying sub-modules, or is referenced by multiple modules as a dependency.
-   - TOP-LEVEL modules: directories directly under project root (or under src/ for src-based layouts) that qualify.
-   - SUB-MODULES: directories INSIDE a top-level module that qualify. Listed in the parent L1 doc's SUBDIRS section.
-   - HIERARCHY RULE: directory X inside top-level module M maps to .prizm-docs/<M>/<X>.prizm, never to .prizm-docs/<X>.prizm.
-   - Exclude .git/, node_modules/, vendor/, build/, dist/, __pycache__/, target/, bin/, .claude/, .codebuddy/, .prizmkit/, .prizm-docs/, dev-pipeline/. If total module count > 30, ask user for include/exclude patterns.
-3. Create .prizm-docs/ directory structure mirroring the source tree exactly. For each top-level module M that has sub-modules, create the subdirectory .prizm-docs/<M>/.
-4. Generate root.prizm (L0) with PROJECT, LANG, FRAMEWORK, BUILD, TEST, ENTRY, MODULE_INDEX with multi-level entries as needed for efficient navigation (constrained by 4KB limit), RULES extracted from CODEBUDDY.md/CLAUDE.md/README/linter configs, PATTERNS, and CROSS_CUTTING (cross-module concerns spanning 2+ modules). Set PRIZM_VERSION: 4. Max 4KB. No UPDATED timestamp — git tracks modification times.
-   - If module count > 15: use MODULE_GROUPS format instead of MODULE_INDEX — group modules by functional domain (3-8 domains, inferred from directory structure and module responsibilities). See PRIZM-SPEC for MODULE_GROUPS format.
-   - For each module entry, auto-generate 3-6 keyword tags by scanning the module's key source files for: exported function/class names, imported library names, domain-specific terms in file/directory names. Add tags in square brackets after the module name (e.g., `- auth [login, session, jwt]: ...`). Tags are optional but recommended for projects with 10+ modules.
-5. Generate L1 .prizm files (structural index only) for ALL modules, each at its correct mirrored path:
-   - Top-level module M → write .prizm-docs/<M>.prizm (include SUBDIRS section with pointers to sub-module docs)
-   - Sub-module S inside M → write .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. Create changelog.prizm with initial entry: `- YYYY-MM-DD | root | add: initialized prizm documentation framework`
-8. Configure UserPromptSubmit hook in platform settings per ${SKILL_DIR}/assets/PRIZM-SPEC.md Section 11.
-9. 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 UPDATED timestamps (git is authority).
-10. Report summary: modules discovered, L1 docs generated, files excluded, warnings.
-
-OUTPUT: List of generated files, module count, and validation results.
+→ Read `${SKILL_DIR}/references/op-init.md` for detailed steps.
 
 ## Operation: Update
 
 Update .prizm-docs/ to reflect recent code changes.
-
 PRECONDITION: .prizm-docs/ exists with root.prizm.
-
-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, CHANGELOG), 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. No UPDATED timestamps — git tracks modification times.
-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 using the L2 GENERATION TEMPLATE. 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 using the L2 GENERATION TEMPLATE. This ensures Update fills documentation gaps left by previous sessions.
-7. Append entries to changelog.prizm using format: `- YYYY-MM-DD | <module-path> | <verb>: <description>`
-8. Enforce size limits: L0 > 4KB -> consolidate. L1 > 4KB -> trim KEY_FILES descriptions, ensure RULES <= 3 entries. L2 > 5KB -> split or archive.
-9. Stage updated .prizm files via `git add .prizm-docs/`
-
-OUTPUT: List of updated/created/skipped docs with reasons.
+→ Read `${SKILL_DIR}/references/op-update.md` for detailed steps.
 
 ## Operation: Status
 
 Check freshness of all .prizm docs.
-
 PRECONDITION: .prizm-docs/ exists with root.prizm.
-
-STEPS:
-1. Get last git modification time of root.prizm via `git log -1 --format="%ai" -- .prizm-docs/root.prizm`.
-2. Count commits since that time via `git log --since="<timestamp>" --oneline | wc -l`.
-3. For each L1/L2 doc, compare git modification time of the .prizm file (`git log -1 --format="%ai" -- <prizm-file>`) against latest git modification of source files in that module (`git log -1 --format="%ai" -- <module-path>/`).
-4. Classify each doc as: FRESH (prizm file updated after latest source change), STALE (source changed more recently than prizm file), MISSING (module exists but no .prizm doc).
-5. Flag any docs exceeding size limits.
-
-OUTPUT: Freshness report table with columns: DOC_PATH | LEVEL | STATUS | PRIZM_LAST_MOD | SOURCE_LAST_MOD.
+→ 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: .prizm-docs/ exists. Module path is valid.
-
-STEPS:
-1. Delete existing L1 and all L2 docs for the specified module.
-2. Re-scan the module directory for files, interfaces, dependencies, subdirectories.
-3. Generate fresh L1 doc with full module analysis.
-4. Generate L2 docs for all sub-modules immediately (unlike init, rebuild generates L2 right away to capture current state).
-5. Update MODULE_INDEX (or MODULE_GROUPS) in root.prizm with new file counts and pointers. Re-evaluate grouping: if total module count > 15 and currently using MODULE_INDEX, convert to MODULE_GROUPS. Regenerate keyword tags for rebuilt modules.
-6. Append rebuild entry to changelog.prizm: `- YYYY-MM-DD | <module-path> | refactor: rebuilt module documentation from scratch`
-7. Validate regenerated docs against size limits and format rules.
-
-OUTPUT: Regenerated doc summary with before/after comparison.
+→ Read `${SKILL_DIR}/references/op-rebuild.md` for detailed steps.
 
 ## Operation: Validate
 
 Check format compliance and consistency of all .prizm docs.
-
 PRECONDITION: .prizm-docs/ exists.
-
-STEPS:
-1. FORMAT CHECK: Verify all .prizm files use KEY: value format. Flag any prose paragraphs, code blocks (```), markdown headers (##), emoji, ASCII art, or horizontal rules. Flag TRAPS entries missing severity prefix ([CRITICAL], [HIGH], or [LOW]). Note: [REVIEW] preceding severity (e.g., `[REVIEW][HIGH]`) is a valid temporary staleness marker, not a format violation.
-2. SIZE CHECK: Verify size limits: L0 <= 4KB, L1 <= 4KB, L2 <= 5KB. Report files exceeding limits with current size.
-3. POINTER CHECK: Verify all arrow (->) references resolve to existing .prizm files. Report broken pointers.
-4. STALENESS CHECK: Compare git modification time of each .prizm file against source directory. Flag docs where source was modified more recently.
-5. COMPLETENESS CHECK: Verify root.prizm has all required fields (PRIZM_VERSION, PROJECT, LANG, MODULE_INDEX or MODULE_GROUPS). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, DEPENDENCIES (no INTERFACES/TRAPS/DECISIONS). Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS.
-6. ANTI-PATTERN CHECK: Flag duplicate information across levels, implementation details in L0/L1, TODO items, session-specific context.
-7. RULES HIERARCHY CHECK: Verify L1/L2 RULES do not contradict root.prizm RULES. L1/L2 may only supplement with module-specific exceptions.
-8. TRAPS STALENESS CHECK: For each L2 doc where TRAPS section has more than 8 entries, verify that TRAPS include staleness metadata (`STALE_IF:` or `REF:` fields). Flag TRAPS without any staleness metadata as `NEEDS_METADATA` — these are not auto-removed, but flagged for the next `/prizmkit-retrospective` to enrich with `STALE_IF:` globs or `REF:` hashes.
-
-OUTPUT: Validation report with PASS/FAIL per check, list of issues with file paths and suggested fixes.
+→ Read `${SKILL_DIR}/references/op-validate.md` for detailed steps.
 
 ## Operation: Migrate
 
 Convert existing documentation to .prizm-docs/ format.
-
-PRECONDITION: Existing docs/ or docs/AI_CONTEXT/ directory with documentation files. No .prizm-docs/ directory (or user confirms overwrite).
+PRECONDITION: Existing docs/ or docs/AI_CONTEXT/ directory. No .prizm-docs/ (or user confirms overwrite).
 
 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, detailed module info -> L2 docs.
+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 .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.
@@ -161,7 +90,7 @@ OUTPUT: Migration report with list of source docs processed, generated .prizm fi
 - **No git history available**: Fall back to filesystem timestamps for freshness checks; warn user that accuracy may be reduced.
 
 ### Key Protocols (reference)
-For detailed protocol specifications, see PRIZM-SPEC:
+For detailed protocol specifications, see prizm-docs-format.md:
 - Progressive Loading: Section 6.1
 - Auto-Update: Section 7.1
 - RULES hierarchy: Section 3.1
@@ -184,5 +113,5 @@ Changed: src/routes/avatar.ts (A), src/models/user.ts (M)
 Updated: .prizm-docs/routes.prizm — added avatar.ts to KEY_FILES, new POST /api/avatar interface
 Updated: .prizm-docs/models.prizm — updated User interface with avatar_url field
 Skipped: .prizm-docs/services.prizm — no changes in services module
-Appended: changelog.prizm — "2026-03-18 | routes | add: avatar upload endpoint"
+Appended: changelog.prizm — "routes | add: avatar upload endpoint"
 ```