prizmkit 1.1.1 → 1.1.4

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

@@ -5,18 +5,16 @@ description: "Incremental .prizm-docs/ maintainer. Performs two jobs: (1) struct
 
 # PrizmKit Retrospective
 
-All project knowledge is maintained in a single store:
-
 | Store | Location | Content | Purpose |
 |-------|----------|---------|---------|
 | **Architecture Index** | `.prizm-docs/` | MODULE, FILES, INTERFACES, DEPENDENCIES, TRAPS, RULES, DECISIONS | AI quickly locates code structure, interfaces, known pitfalls, and key design decisions |
 
-**This skill performs two jobs in one pass:**
+**This skill handles both structural sync and knowledge injection in one pass:**
 
 1. **Structural Sync** — reflect what changed in code → `.prizm-docs/` (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
-2. **Architecture Knowledge** — inject TRAPS, RULES, and DECISIONS → `.prizm-docs/`. All knowledge is consolidated in `.prizm-docs/`.
+2. **Architecture Knowledge** — inject TRAPS, RULES, and DECISIONS → `.prizm-docs/`
 
-No other skill writes to `.prizm-docs/`. This is the sole writer during ongoing development. For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` instead.
+For initial doc setup, validation, or migration, use `/prizmkit-prizm-docs` instead.
 
 ## When to Use
 
@@ -34,122 +32,19 @@ No other skill writes to `.prizm-docs/`. This is the sole writer during ongoing
 
 ---
 
-## Job 1: Structural Sync
-
-Reflect code changes in `.prizm-docs/` so the project map stays accurate.
-
-### Steps
-
-**1a.** Get changed files:
-```bash
-git diff --cached --name-status
-```
-If nothing staged, fallback:
-```bash
-git diff --name-status
-```
-
-**1b.** Read `.prizm-docs/root.prizm` to get MODULE_INDEX. Map each changed file to its module.
-
-**1c.** Classify changes:
-- `A` (added) → add to KEY_FILES, check for new INTERFACES
-- `D` (deleted) → remove from KEY_FILES, update FILE count
-- `M` (modified) → check if public interfaces or dependencies changed
-- `R` (renamed) → update all path references
-
-**1d.** Update affected docs (bottom-up: L2 → L1 → L0):
-
-- **L2**: If L2 exists → update KEY_FILES, INTERFACES, DATA_FLOW, DEPENDENCIES, CHANGELOG, TRAPS, DECISIONS. If L2 does NOT exist AND the module has Added or Modified source files in the current diff with meaningful logic (not trivial config) → create L2 using the L2 GENERATION TEMPLATE, then populate from source.
-- **L1**: Update FILES count, KEY_FILES (if major files added/removed), DEPENDENCIES (if module-level deps changed). **L1 does NOT contain INTERFACES, DATA_FLOW, TRAPS, or DECISIONS** — those belong in L2 only.
-- **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update CROSS_CUTTING if cross-module concerns changed. Update only if structural change (module added/removed).
-
-**1d-migrate.** Legacy TRAPS format migration (opportunistic):
-While updating an affected L1/L2 doc, if you encounter TRAPS entries **without** a severity prefix (e.g., `- foo | FIX: bar` instead of `- [LOW] foo | FIX: bar`), prepend `[LOW]` as a conservative default. This clears legacy format debt incrementally — only in files already being touched, never as a bulk operation.
-
-**1e.** If new directory qualifies as a module (per MODULE_DISCOVERY_CRITERIA in PRIZM-SPEC Section 9.1 Step 2) and matches no existing module:
-1. Create L1 doc immediately, add to MODULE_INDEX.
-2. If the current diff includes Added or Modified source files with meaningful logic in this module → create L2 immediately using the L2 GENERATION TEMPLATE. Otherwise defer L2 to the next session that touches this module.
-
-**1f.** Enforce size limits:
-- L0 > 4KB → consolidate MODULE_INDEX
-- L1 > 4KB → trim KEY_FILES descriptions, ensure RULES <= 3 entries
-- L2 > 5KB → archive old CHANGELOG entries
-
-**SKIP structural sync if**: only internal implementation changed (no interface/dependency impact), only comments/whitespace, only .prizm files. **DO NOT skip** test file changes or bug fixes — they may reveal TRAPS worth capturing in L2.
-
-**1g. TRAPS staleness check** (only when an L2 doc's TRAPS section has > 10 entries):
+### Job 1: Structural Sync (always runs)
+Synchronize `.prizm-docs/` structure with actual codebase changes from this session.
+→ Read `${SKILL_DIR}/references/structural-sync-steps.md` for the detailed 7-step procedure (1a–1g).
 
-Perform a quick staleness scan on existing TRAPS to prevent unbounded accumulation:
-1. If a TRAP has `STALE_IF:` and the glob-matched files no longer exist (verified via `ls`) → delete the TRAP entry, append CHANGELOG: `remove: archived stale TRAP - <summary>`
-2. If a TRAP has `REF:` → check if the referenced file still exists and the REF commit is less than 180 days old (via `git log --since="180 days ago" <hash> 2>/dev/null`). If the file is deleted OR the REF commit is older than 180 days → prepend `[REVIEW]` to the severity, signaling it needs verification during the next retrospective Job 2
-3. Process at most 5 of the oldest TRAPS per L2 doc per session (to bound context cost)
-
-This step is lightweight — it only triggers when TRAPS exceed 10 entries, and processes at most 5 per run.
+**Key outputs**: Updated L1 file counts, L2 INTERFACES/DATA_FLOW, changelog entries, stale TRAPS cleanup.
 
 ---
 
-## Job 2: Architecture Knowledge Injection → `.prizm-docs/`
-
-Extract TRAPS, RULES, and DECISIONS from development work and inject into `.prizm-docs/`. All project knowledge lives in `.prizm-docs/` — no external memory files.
-
-`.prizm-docs/` is the **single source of project knowledge**: it tells AI *what code exists, how it connects, what pitfalls to avoid, and why key design choices were made*.
-
-### When to run Job 2
-
-- Feature completion (spec + plan + implementation done)
-- Bugfix that reveals a non-obvious failure mode (the root cause is itself a TRAP)
-- Refactor that revealed structural insights
-- **Skip for**: trivial fixes, config changes, dependency bumps
-
-### Steps
-
-**2a.** Gather context — read the **actual code that was changed** plus any available artifacts:
-
-- `git diff HEAD` — the real source of truth for what happened
-- `.prizmkit/specs/###-feature-name/context-snapshot.md` — read the '## Implementation Log' section (Dev's changes, decisions, discoveries) and '## Review Notes' section (Reviewer's findings). These are the **preferred source** for pre-categorized decisions and findings. If these sections exist, prefer them over re-extracting from git diff.
-- `.prizmkit/specs/###-feature-name/plan.md` — if feature work, read planned vs actual
-- `.prizmkit/bugfix/<id>/fix-report.md` — if bugfix, read what was discovered
-- `.prizmkit/specs/###-feature-name/failure-log.md` — if a previous session failed, read DISCOVERED_TRAPS. These are high-value TRAPS because they come from actual failures — prioritize injecting them into `.prizm-docs/`
-- The relevant `.prizm-docs/` L1/L2 docs for affected modules
-
-**2b.** Extract knowledge from what was **observed in code**, not invented:
-
-**TRAPS** (highest priority) — things that look safe but break:
-- Minimal format: `- [SEVERITY] <description> | FIX: <approach>`
-- Full format: `- [SEVERITY] <description> | FIX: <approach> | REF: <hash> | STALE_IF: <glob>`
-- Source: actual bugs hit, surprising behavior discovered in code, non-obvious coupling
-
-**TRAPS severity classification**:
-- `[CRITICAL]`: data loss, security, financial error, system crash
-- `[HIGH]`: functional failure, silent error, interface incompatibility
-- `[LOW]`: misleading naming, non-intuitive API, minor performance issue
-
-When writing TRAPS:
-- Severity prefix is MANDATORY (e.g., `[CRITICAL]`, `[HIGH]`, `[LOW]`)
-- OPTIONAL: append `| REF: <7-char-hash>` when you know the relevant commit (for traceability)
-- OPTIONAL: append `| STALE_IF: <glob>` when the TRAP is tightly coupled to specific files (for auto-expiry detection)
-
-**Consuming [REVIEW] markers** (from staleness check 1g):
-- If you encounter a TRAP prefixed with `[REVIEW]` (e.g., `[REVIEW][HIGH] ...`), verify whether the trap is still valid by checking the current code. If still valid: remove the `[REVIEW]` prefix, keeping the severity. If no longer relevant: delete the TRAP entry and append CHANGELOG.
-
-**RULES** — conventions established or constraints discovered:
-- Format: `- MUST/NEVER/PREFER: <rule>`
-- Source: patterns that proved necessary during implementation
-
-**DECISIONS** — key design choices that affect future development:
-- Format: `- <what was decided> — <rationale>`
-- Source: non-obvious design choices, interface conventions, cross-module contracts
-- Only record decisions that a future AI session would benefit from knowing
-- Do NOT record obvious implementation details that can be derived by reading the code
-
-**QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizm-docs/` and this entry, does it gain actionable understanding?" If not, discard. Do not record trivially observable code patterns — the AI can read the code directly.
-
-**2c.** Inject into the correct `.prizm-docs/` file:
-- Module-level TRAPS/RULES/DECISIONS → the affected **L2** `.prizm` file. If the target L2 does not exist, create it first using the L2 GENERATION TEMPLATE before injecting knowledge. (TRAPS/DECISIONS/RULES belong in L2, not L1.)
-- Project-level RULES/PATTERNS → `root.prizm`
-- Cross-module concerns spanning 2+ modules → `root.prizm` CROSS_CUTTING section
+### Job 2: Knowledge Injection (conditional — skip for pure refactors)
+Inject newly discovered project knowledge (TRAPS, RULES, DECISIONS) into architecture docs.
+→ Read `${SKILL_DIR}/references/knowledge-injection-steps.md` for the detailed 3-step procedure (2a–2c).
 
-**RULE**: Only add genuinely new information. Never duplicate existing entries. Never rewrite entire files.
+**Key outputs**: New TRAPS entries, RULES updates, DECISIONS records in relevant L1/L2 docs and root.prizm.
 
 ---
 
@@ -178,7 +73,7 @@ In the dev-pipeline, this skill is the **single doc maintenance step** before co
 implement → code-review → retrospective (architecture sync) → committer (pure commit)
 ```
 
-The pipeline enforces a **docs pass condition**: `.prizm-docs/` must show changes in the final commit. This skill is the sole satisfier of that requirement.
+The pipeline enforces a **docs pass condition**: `.prizm-docs/` must show changes in the final commit. This skill satisfies that requirement.
 
 ## HANDOFF Chain