prizmkit 1.1.1 → 1.1.3

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

@@ -1,12 +1,10 @@
 ---
 name: "prizmkit-implement"
-description: "Execute implementation following plan.md tasks. Respects task ordering, dependencies, and TDD approach. Marks tasks complete as they finish. Use this skill whenever you're ready to write code for a planned feature, or for fast-path changes where the user describes a simple fix directly. Trigger on: 'implement', 'build', 'code it', 'start coding', 'develop', 'write the code'. (project)"
+description: "Execute plan.md tasks with TDD approach. Respects task ordering and dependencies. Use after /prizmkit-plan (or /prizmkit-analyze). Trigger on: 'implement', 'build', 'code it', 'start coding', 'execute', 'write the code'. (project)"
 ---
 
 # PrizmKit Implement
 
-Execute implementation by following the task breakdown in plan.md. Respects task ordering, dependency constraints, and applies a TDD approach where applicable. Marks each task complete as it finishes.
-
 ### When to Use
 - After `/prizmkit-plan` (or `/prizmkit-analyze`) when ready to write code
 - User says "implement", "build", "code it", "start coding", "develop"
@@ -49,53 +47,8 @@ Execute implementation by following the task breakdown in plan.md. Respects task
    f. Error handling: sequential tasks stop on failure (later tasks may depend on this one). Parallel `[P]` tasks continue — report all failures at the end.
 5. At each checkpoint: verify build passes and tests pass. Checkpoints catch integration errors early — skipping them means cascading failures in later phases that are much harder to debug.
 6. After all tasks: run full test suite
-7. **Deploy guide update** (only when new frameworks/tools were added):
-   - Check if any dependency manifests were modified in this session:
-     ```bash
-     git diff --name-only HEAD -- package.json requirements*.txt Pipfile pyproject.toml go.mod Cargo.toml pom.xml build.gradle Gemfile composer.json docker-compose*.yml Dockerfile .tool-versions 2>/dev/null
-     ```
-   - If no manifest files changed → skip this step entirely
-   - If manifest files changed, scan for **newly added** dependencies (not version bumps):
-     ```bash
-     git diff -U0 HEAD -- package.json requirements*.txt Pipfile pyproject.toml go.mod Cargo.toml pom.xml build.gradle Gemfile composer.json docker-compose*.yml Dockerfile .tool-versions 2>/dev/null | grep '^\+' | grep -v '^\+\+\+' | head -30
-     ```
-   - For each genuinely new framework/tool, record in `deploy_guide.md` at project root:
-
-     | Field | Description | Source |
-     |-------|-------------|--------|
-     | **Name** | Framework/tool name | Package name from manifest |
-     | **Version** | Installed version or constraint | Version spec from manifest |
-     | **Purpose** | Why it was introduced | You just added it — you know why |
-     | **Install Command** | How to install locally | Standard install command for the ecosystem |
-     | **Key Config** | Config files or env vars needed | Config files you just created/modified |
-     | **Notes** | Setup gotchas, required services | Docker services, manual steps, env vars |
-
-   - Template for `deploy_guide.md`:
-     ```markdown
-     # Deploy Guide
-
-     > Auto-maintained by PrizmKit. Manual edits are preserved.
-     > Last updated: YYYY-MM-DD
-
-     ## Frameworks & Tools
-
-     ### <Framework Name>
-
-     - **Version**: <version constraint>
-     - **Purpose**: <why this framework is used>
-     - **Install**:
-       ```bash
-       <install command>
-       ```
-     - **Key Config**:
-       - `<config file or env var>`: <description>
-     - **Notes**:
-       - <any setup gotchas, required external services, manual steps>
-     ```
-
-   - **Update rules**: create file if absent; append new sections if file exists; update version if framework already documented; preserve manually added content; keep entries sorted alphabetically
-   - **Filter out**: patch version bumps of existing deps, dev-only tools needing no setup (linters, formatters), transitive/lock-file-only changes
-   - Stage the file: `git add deploy_guide.md`
+7. **Deploy guide update** — only when dependency manifests (package.json, requirements.txt, etc.) changed during this task.
+      → Read `${SKILL_DIR}/references/deploy-guide-protocol.md` and follow its protocol.
 8. Output implementation summary with pass/fail status
 
 ## Task Format in plan.md

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

@@ -63,16 +63,8 @@ BROWNFIELD WORKFLOW (existing project):
 3. Identify entry points by language convention
 4. Catalog dependencies (external packages)
 5. Count source files per directory
-6. Detect detailed tech stack (adaptive — only include fields that apply to this project):
-   - **Language & Runtime**: e.g. TypeScript + Node.js 20, Python 3.11, Go 1.22
-   - **Frontend framework** (if applicable): React, Vue.js, Angular, Next.js, Svelte, etc.
-   - **Frontend styling** (if applicable): Tailwind CSS, SCSS, Styled Components, Material UI, etc.
-   - **Backend framework** (if applicable): Express.js, FastAPI, Django, NestJS, Gin, etc.
-   - **Database** (if applicable): PostgreSQL, MySQL, MongoDB, Redis, SQLite — detected from deps or `docker-compose.yml`
-   - **ORM** (if applicable): Prisma, Drizzle, TypeORM, SQLAlchemy, Mongoose, etc.
-   - **Bundler** (if applicable): Vite, Webpack, esbuild, Rollup, Turborepo
-   - **Testing**: Vitest, Jest, pytest, Go test, etc.
-   - **Project type** (inferred): `frontend` | `backend` | `fullstack` | `library` | `cli` | `monorepo`
+6. Detect detailed tech stack (adaptive — only include fields that apply):
+   → Read `${SKILL_DIR}/references/tech-stack-catalog.md` for the full field catalog.
 
    **IMPORTANT**: Not all projects have all fields. A pure backend API will have no `frontend_framework` or `frontend_styling`. A library may have no database. Only record what is actually detected — never generate empty or placeholder values.
 
@@ -90,55 +82,7 @@ Invoke prizmkit-prizm-docs (Init operation), passing the two-tier module structu
   - `.prizmkit/specs/` (empty)
 
 3b. Write detected tech stack to `.prizmkit/config.json`:
-
-   **Merge strategy** (handles re-init without losing user edits):
-   - Read existing `config.json` if present
-   - If `tech_stack` field exists AND `_auto_detected` is `false` or absent:
-     → **SKIP** — user has manually configured tech stack, preserve their settings
-   - If `tech_stack` field exists AND `_auto_detected` is `true`:
-     → **MERGE** — overwrite auto-detected values with new detection results, but preserve any keys the user added manually (keys not in the new detection result)
-   - If `tech_stack` field does NOT exist:
-     → **WRITE** full detected tech stack with `"_auto_detected": true`
-   - Only include fields that were actually detected (no empty/null values)
-
-   Example config.json after init (fullstack project):
-   ```json
-   {
-     "adoption_mode": "passive",
-     "platform": "claude",
-     "tech_stack": {
-       "language": "TypeScript",
-       "runtime": "Node.js 20",
-       "frontend_framework": "React",
-       "frontend_styling": "Tailwind CSS",
-       "backend_framework": "Express.js",
-       "database": "PostgreSQL",
-       "orm": "Prisma",
-       "testing": "Vitest",
-       "bundler": "Vite",
-       "project_type": "fullstack",
-       "_auto_detected": true
-     }
-   }
-   ```
-
-   Example config.json after init (pure Python backend):
-   ```json
-   {
-     "adoption_mode": "passive",
-     "platform": "claude",
-     "tech_stack": {
-       "language": "Python",
-       "runtime": "Python >=3.11",
-       "backend_framework": "FastAPI",
-       "database": "PostgreSQL",
-       "orm": "SQLAlchemy",
-       "testing": "pytest",
-       "project_type": "backend",
-       "_auto_detected": true
-     }
-   }
-   ```
+   → Read `${SKILL_DIR}/references/config-schema.md` for merge strategy, field definitions, and examples.
 
 **Step 4: Hook & Settings Configuration**
 
@@ -165,16 +109,7 @@ Tech stack detected:
   Project type: fullstack
 ```
 
-For a pure backend Python project, the report would show:
-```
-Tech stack detected:
-  Language:     Python
-  Runtime:      Python >=3.11
-  Backend:      FastAPI
-  Database:     PostgreSQL (SQLAlchemy)
-  Testing:      pytest
-  Project type: backend
-```
+Adapt fields to match project type — only show detected fields.
 
 Saved to: `.prizmkit/config.json` → `tech_stack` field
 
@@ -243,12 +178,7 @@ Next: Use /prizmkit-plan to start your first feature
 ```
 
 UPDATE SUPPLEMENT (runs after tech stack merge in Update mode):
-
-1. **Module scan**: Re-scan project directories using the same TWO-TIER model from Step 1. Compare discovered modules against existing MODULE_INDEX in root.prizm.
-2. **Missing L1 check**: For any discovered module with no corresponding L1 `.prizm` doc → create L1 immediately and add to MODULE_INDEX.
-3. **Missing L2 check**: For any module/sub-module that has source files with meaningful logic but no L2 `.prizm` doc → create L2 using the L2 GENERATION TEMPLATE. Judgment call: skip trivial wrapper directories or single-config modules.
-4. **Stale L1 check**: For existing L1 docs, verify FILES count and KEY_FILES are still accurate. Update if source directory contents have changed significantly.
-5. **Report**: Include in the Update report: modules added, L1 docs created, L2 docs created, stale docs refreshed.
+→ Read `${SKILL_DIR}/references/update-supplement.md` for the 5-step gap-fill procedure.
 
 **Re-init after PrizmKit upgrade (existing config preserved):**
 ```
@@ -270,5 +200,3 @@ Documentation gap-fill:
 
 Merged into .prizmkit/config.json (2 fields updated, user overrides preserved)
 ```
-
-IMPORTANT: Use `${SKILL_DIR}` placeholder for all path references. Never hardcode absolute paths.

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

@@ -1,12 +1,10 @@
 ---
 name: "prizmkit-plan"
-description: "Specify and plan features in one step. Transforms natural language into structured spec.md, then generates plan.md with architecture and executable tasks. Use this skill whenever the user wants to define a feature, write requirements, design implementation, or break work into tasks. Trigger on: 'specify', 'plan', 'new feature', 'I want to add...', 'I want to build...', 'architect', 'design', 'break it down', 'create tasks', 'how to build', 'let's add', 'feature idea'. Always use before /prizmkit-implement. Skip specify phase for bug fixes or simple refactors. (project)"
+description: "Specify and plan features: natural language → spec.md → plan.md with architecture and executable tasks. Supports feature, refactor, and bugfix modes. Use before /prizmkit-implement. Trigger on: 'specify', 'plan', 'new feature', 'I want to add/build...', 'architect', 'design', 'break it down', 'create tasks'. (project)"
 ---
 
 # PrizmKit Plan
 
-Define WHAT to build, then design HOW to build it — in one continuous flow. Phase 0 produces `spec.md` (requirements), Phase 1-2 produce `plan.md` (architecture + tasks).
-
 ### When to Use
 - New feature — user says "specify", "plan", "new feature", "I want to add..."
 - Before `/prizmkit-implement` — to create the spec + task breakdown
@@ -99,15 +97,6 @@ If no input document exists, prompt user to describe the feature (triggers Phase
 
 **HANDOFF:** `/prizmkit-implement`
 
-## Handling Vague Inputs
-
-When the user's description is vague:
-1. Extract what IS clear and write it into the spec
-2. Mark ambiguous parts with `[NEEDS CLARIFICATION]` + recommended default
-3. Auto-clarification (Phase 0, step 9) resolves interactively before planning
-
-Never block progress — always produce a usable spec, even with open questions.
-
 ## Example
 
 **Input:** "I want users to upload avatars"

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

@@ -124,7 +124,7 @@ 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 <= 3KB, L2 <= 5KB. Report files exceeding limits with current size.
+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). Verify L1 docs have MODULE, FILES, RESPONSIBILITY, DEPENDENCIES (no INTERFACES/TRAPS/DECISIONS). Verify L2 docs have MODULE, FILES, KEY_FILES, DEPENDENCIES, INTERFACES, TRAPS.
@@ -157,29 +157,11 @@ OUTPUT: Migration report with list of source docs processed, generated .prizm fi
 - **Size limit exceeded**: For L0, consolidate MODULE_INDEX entries. For L1, move implementation details to L2. For L2, archive CHANGELOG entries older than 90 days.
 - **No git history available**: Fall back to filesystem timestamps for freshness checks; warn user that accuracy may be reduced.
 
-## Progressive Loading Protocol
-
-When working in a project with .prizm-docs/:
-
-- ON SESSION START: Always read .prizm-docs/root.prizm (L0). This is the project map.
-- ON TASK: Read L1 docs for relevant modules referenced in MODULE_INDEX.
-- ON FILE EDIT: Read L2 doc before modifying files. Check TRAPS and DECISIONS sections. If L2 does not exist and you are creating/modifying significant source files in this module → generate L2 using the L2 GENERATION TEMPLATE before proceeding.
-- ON DEEP READ: If you need deep understanding of a module without modifying it, generate L2 if it doesn't exist.
-- NEVER load all .prizm docs at once. Progressive loading saves tokens.
-- BUDGET: Typical task should consume 3000-5000 tokens of Prizm docs total.
-
-## Auto-Update Protocol
-
-- BEFORE EVERY COMMIT: Run `/prizmkit-retrospective` which is the **sole maintainer** of .prizm-docs/. It handles structural sync and TRAPS/RULES/DECISIONS injection to `.prizm-docs/`.
-- The UserPromptSubmit hook will remind you automatically when commit intent is detected.
-- `/prizmkit-committer` does NOT update .prizm-docs/ — it only commits what is already staged.
-- NEVER rewrite entire .prizm files. Only update affected sections.
-
-## RULES Hierarchy
-
-- root.prizm RULES are authoritative and apply project-wide.
-- L1/L2 RULES only supplement root.prizm with module-specific exceptions.
-- If L1/L2 RULES contradict root.prizm RULES, root.prizm takes precedence.
+### Key Protocols (reference)
+For detailed protocol specifications, see PRIZM-SPEC:
+- Progressive Loading: Section 6.1
+- Auto-Update: Section 7.1
+- RULES hierarchy: Section 3.1
 
 ## Examples
 

package/bundled/skills/prizmkit-prizm-docs/assets/PRIZM-SPEC.md

@@ -8,6 +8,27 @@ LICENSE: MIT
 
 ---
 
+## Table of Contents
+
+1. Overview (L32–49)
+2. Architecture (L50–127)
+3. Document Format Specification (L128–308)
+4. Format Conventions (L309–321)
+5. Path Mapping Rules (L322–351)
+6. Progressive Loading Protocol (L352–411)
+7. Auto-Update Protocol (L412–491)
+8. Anti-Patterns (L492–511)
+9. Initialization Procedure (L512–646)
+10. Skill Definition (L647–768)
+11. Hook Configuration (L769–823)
+12. Language-Specific Initialization Hints (L824–857)
+13. Minimal Viable Prizm (L858–875)
+14. Version History (L876–920)
+15. Conflict Resolution (L921–978)
+16. Version Migration (L979–1087)
+
+---
+
 # SECTION 1: OVERVIEW
 
 WHAT: Prizm is a self-maintaining documentation system where AI reads, generates, updates, and loads project context progressively.

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