prizmkit 1.0.45 → 1.0.66

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

@@ -1,79 +1,156 @@
 ---
 name: "prizmkit-retrospective"
-description: "Post-feature retrospective. Extracts lessons from completed features, updates Prizm docs TRAPS and RULES. Invoke after feature completion. (project)"
+description: "Incremental .prizm-docs/ maintainer — the sole writer during ongoing development. Performs two jobs after code changes: (1) structural sync — update KEY_FILES/INTERFACES/DEPENDENCIES to reflect code changes, and (2) knowledge injection — extract TRAPS/RULES/DECISIONS from completed work. Run after code review passes and before committing. For initial doc setup, validation, or migration, use /prizmkit-prizm-docs instead. Trigger on: 'retrospective', 'retro', 'update docs', 'sync docs', 'wrap up', 'done with feature', 'feature complete'. (project)"
 ---
 
 # PrizmKit Retrospective
 
-Post-feature retrospective analysis that extracts lessons learned, updates Prizm documentation with discovered traps and rules, and documents improvements for future reference.
+**The sole maintainer of `.prizm-docs/` project memory.** No other skill writes to `.prizm-docs/`. This skill performs two distinct jobs in one pass:
 
-### When to Use
-- After completing a feature (spec, plan, tasks, implementation all done)
-- User says "retrospective", "retro", "lessons learned", "what did we learn"
-- Before starting a new major feature (to apply lessons from the last one)
+1. **Structural Sync** — reflect what changed in code (KEY_FILES, INTERFACES, DEPENDENCIES, file counts)
+2. **Knowledge Injection** — extract what was learned (TRAPS, RULES, DECISIONS)
 
-### prizmkit.retrospective
+Both jobs are necessary because `.prizm-docs/` exists to help AI understand the project. Structural accuracy tells AI *what exists*; knowledge tells AI *why it exists and what to watch out for*.
 
-PRECONDITION: Completed feature with spec.md, plan.md, tasks.md in .prizmkit/specs/
+## When to Use
+
+- **Before every commit** (mandatory in pipeline) — ensures docs and code are in sync
+- After completing a feature (spec, plan, implementation all done)
+- After code review passes (PASS or PASS WITH WARNINGS)
+- User says "retrospective", "retro", "update docs", "sync docs", "wrap up"
+- After refactoring or bugfix cycles (structural sync + optional TRAPS update)
+
+## When NOT to Use
+
+- 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
+- User just wants to commit without doc update — use `/prizmkit-committer` directly (but pipeline will flag `docs_missing`)
+
+---
+
+## 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 exists): Update KEY_FILES, INTERFACES, DEPENDENCIES, CHANGELOG, UPDATED timestamp
+- **L1**: Update FILES count, KEY_FILES (if major files added/removed), INTERFACES (if public API changed), UPDATED timestamp
+- **L0 root.prizm**: Update MODULE_INDEX file counts only if counts changed. Update UPDATED only if structural change (module added/removed).
+
+**1e.** If new directory with 3+ source files matches no existing module: create L1 doc immediately, add to MODULE_INDEX, defer L2.
+
+**1f.** Enforce size limits:
+- L0 > 4KB → consolidate MODULE_INDEX
+- L1 > 3KB → move details to L2
+- L2 > 5KB → archive old CHANGELOG entries
+
+**SKIP structural sync if**: only internal implementation changed (no interface/dependency impact), only comments/whitespace, only test files, only .prizm files, bug fixes with no interface change.
+
+---
+
+## Job 2: Knowledge Injection
+
+Extract what was learned and inject it into the modules where AI will read it. This job has value **only when real development work was done** — not for trivial changes.
+
+### When to run Job 2
+
+- Feature completion (spec + plan + implementation done)
+- Bugfix with a genuinely new pitfall discovered
+- Refactor that revealed structural insights
+- **Skip for**: trivial fixes, config changes, dependency bumps
 
 ### Steps
 
-#### Step 1: Gather Feature Artifacts
-Read all feature artifacts from .prizmkit/specs/###-feature-name/:
-- spec.md (original requirements and acceptance criteria)
-- plan.md (architecture decisions and implementation plan)
-- tasks.md (task breakdown and status)
-- data-model.md (if exists)
-- contracts/ directory (if exists)
-
-#### Step 2: Analyze Implementation
-Compare planned vs actual:
-- Tasks completed vs skipped — why were tasks skipped?
-- Architecture deviations from plan — what changed and why?
-- Unexpected challenges encountered — what surprised us?
-- Time-intensive areas — what took longer than expected?
-
-#### Step 3: Extract Lessons
-Categorize findings:
-- **What went well** (reinforce these patterns)
-- **What went wrong** (create anti-patterns to avoid)
-- **What was surprising** (new patterns to document)
-- **What would you do differently** (improvement candidates)
-
-NOTE: If bug fixes were performed during this feature's implementation, they are refinements of the feature itself (completing its intended behavior), NOT separate features. Do not create separate documentation entries or REGISTRY records for bug fixes.
-
-#### Step 4: Generate Retrospective Document
-Write retrospective.md in .prizmkit/specs/###-feature-name/:
-```markdown
-# Retrospective: <feature-name>
-Date: YYYY-MM-DD
-
-## Summary Statistics
-- Tasks total: N
-- Tasks completed: N
-- Tasks skipped: N (with reasons)
-
-## Key Decisions
-- Decision: <what> | Outcome: <good/bad/neutral> | Lesson: <takeaway>
-
-## Patterns Discovered
-- Pattern: <name> | Context: <when to apply> | Benefit: <why>
-
-## Anti-Patterns Discovered
-- Anti-pattern: <name> | Context: <when it occurred> | Fix: <what to do instead>
-
-## Improvement Suggestions
-- Skill: <skill-name> | Suggestion: <what to improve>
+**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/plan.md` — if feature work, read planned vs actual
+- `.prizmkit/bugfix/<id>/fix-report.md` — if bugfix, read what was discovered
+- 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:
+- Format: `- <what looks safe but is dangerous> | FIX: <correct approach>`
+- Source: actual bugs hit, surprising behavior discovered in code, non-obvious coupling
+
+**RULES** — conventions established or constraints discovered:
+- Format: `- MUST/NEVER/PREFER: <rule>`
+- Source: patterns that proved necessary during implementation
+
+**DECISIONS** — architecture choices made and why:
+- Format: `- [YYYY-MM-DD] <decision and rationale>`
+- Format: `- REJECTED: <approach> — <why it failed>`
+- Source: alternatives tried, design trade-offs made
+
+**QUALITY GATE**: Every item must answer: "If a new AI session reads only `.prizm-docs/` and this entry, does it gain actionable understanding that prevents mistakes or accelerates work?" If not, discard.
+
+**2c.** Inject into the correct `.prizm-docs/` file:
+- Module-level TRAPS/RULES/DECISIONS → the affected L1 or L2 `.prizm` file
+- Project-level RULES/PATTERNS → `root.prizm`
+
+**RULE**: Only add genuinely new information. Never duplicate existing entries. Never rewrite entire files.
+
+---
+
+## Final: Changelog + Stage
+
+**3a.** Append to `.prizm-docs/changelog.prizm`:
+- Format: `- YYYY-MM-DD | <module-path> | <verb>: <one-line description>`
+- Verbs: add, update, fix, remove, refactor, rename, deprecate
+- One entry per meaningful change, not one per file
+
+**3b.** Stage all doc changes:
+```bash
+git add .prizm-docs/
 ```
 
-#### Step 5: Update Prizm Docs
-For each lesson learned, update the relevant `.prizm-docs/` files:
-- Add discovered pitfalls to the affected module's TRAPS section
-- Add new conventions or rules to the affected module's RULES section
-- Append decisions to DECISIONS section with rationale
-- Update changelog.prizm with retrospective findings
-
-#### Step 6: Handoff
-Suggest next action:
-- `prizmkit.specify` — start next feature
-- No action needed — just documenting for future reference
+**3c.** Handoff:
+- `/prizmkit-committer` — proceed to commit
+
+---
+
+## Integration with Pipeline
+
+In the dev-pipeline, this skill is the **single doc maintenance step** before commit:
+
+```
+implement → code-review → retrospective (memory maintenance) → 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.
+
+## HANDOFF Chain
+
+| From | To | Condition |
+|------|----|-----------|
+| `prizmkit-code-review` | **this skill** | Review passes or work is complete |
+| **this skill** | `prizmkit-committer` | Memory maintained, ready to commit |
+| `prizmkit-committer` | — | Committed |
+
+## Output
+
+- `.prizm-docs/*.prizm` — Structurally synced + knowledge enriched
+- `.prizm-docs/changelog.prizm` — Appended entries
+- All changes staged via `git add .prizm-docs/`

package/bundled/skills/prizmkit-retrospective/assets/retrospective-template.md

@@ -0,0 +1,13 @@
+# Retrospective: [FEATURE_NAME]
+Date: YYYY-MM-DD
+
+## Knowledge Captured
+- TRAPS added: N (list affected modules)
+- RULES added: N (list affected modules)
+- DECISIONS recorded: N (list affected modules)
+
+## Key Insights
+- [insight]: [why it matters for future work]
+
+## .prizm-docs/ Updates
+- [file]: [what was updated]

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

@@ -1,24 +1,34 @@
 ---
 name: "prizmkit-specify"
-description: "Create structured feature specifications from natural language. Invoke when starting a new feature, user says 'specify', 'define feature', or 'write requirements'. (project)"
+description: "Create structured feature specifications from natural language. Use this skill whenever the user wants to define a new feature, describe what to build, or write requirements. Trigger on: 'specify', 'define feature', 'write requirements', 'new feature', 'what should we build', 'I want to add...', 'I want to build...', 'let's add', 'let's build', 'feature idea', or when the user describes a feature they want. This is the first step in the full dev workflow — always use before /prizmkit-plan. Skip for bug fixes, config tweaks, or simple refactors (use fast path). (project)"
 ---
 
 # PrizmKit Specify
 
 Create structured feature specifications from natural language descriptions. This skill transforms a feature idea into a well-structured spec with user stories, acceptance criteria, and scope boundaries.
 
-## Commands
+### When to Use
+- Starting a new feature — user says "specify", "define feature", "new feature", "I want to add..."
+- Before `/prizmkit-plan` — to define WHAT will be built before deciding HOW
+- When a feature idea needs to be formalized before implementation
+- When multiple stakeholders need to agree on scope before coding starts
 
-### prizmkit.specify
+### When NOT to Use
+- Bug fixes with clear root cause → use fast path (`/prizmkit-plan` simplified → `/prizmkit-implement` → `/prizmkit-committer`)
+- Config tweaks, typo fixes, simple refactors → edit directly
+- Documentation-only changes → no spec needed
+- User already has a detailed spec → skip to /prizmkit-plan
 
-Create a new feature specification.
-
-**STEPS:**
+## Execution Steps
 
 1. Ask user for feature description (natural language)
 2. Auto-generate 2-4 word feature slug from description
-3. Determine next feature number by scanning `.prizmkit/specs/`
-4. Create directory: `.prizmkit/specs/###-feature-name/`
+3. Determine next feature number by scanning `.prizmkit/specs/`:
+   - List existing `###-*` directories and find the highest numeric prefix
+   - Next number = highest + 1 (zero-padded to 3 digits)
+   - Append a short timestamp suffix (`-MMDD`) to prevent collisions in concurrent sessions. Example: `004-user-avatar-0319/`
+   - If `.prizmkit/specs/` is empty or doesn't exist, start at `001`
+4. Create directory: `.prizmkit/specs/###-feature-name-MMDD/`
 5. Load project context (use first available source):
    - If `.prizmkit/specs/###-feature-name/context-snapshot.md` exists → read Section 3 'Prizm Context' from it (do NOT re-read `.prizm-docs/` files)
    - Otherwise → read `.prizm-docs/root.prizm`
@@ -35,14 +45,58 @@ Create a new feature specification.
    - Check: No more than 3 `[NEEDS CLARIFICATION]` markers?
 8. Output: `spec.md` path and summary
 
-**KEY RULES:**
-- Focus on WHAT and WHY, never HOW (no tech stack details)
-- Max 3 `[NEEDS CLARIFICATION]` markers
-- Every user story MUST have at least one acceptance criterion in Given/When/Then format
-- Scope boundaries MUST be explicitly defined
-- Feature numbers are zero-padded to 3 digits (e.g., `001`, `012`)
+## Writing Principles
+
+- **Focus on WHAT and WHY, never HOW** — the spec describes the problem space; implementation choices belong in plan.md. Mixing in tech stack details couples the spec to a specific solution and makes it harder to explore alternatives during planning.
+- **Every user story needs acceptance criteria** in Given/When/Then format — without them, the implementer has no way to verify the feature works correctly, and the code reviewer has no baseline to check against.
+- **Scope boundaries must be explicit** — without "Out of scope" boundaries, implementers tend to gold-plate features with capabilities nobody asked for, wasting time and adding complexity.
+- **Max 3 `[NEEDS CLARIFICATION]` markers** — more than 3 means the feature idea isn't mature enough to spec. Suggest the user think through the concept further and return, or use `/prizmkit-clarify` to resolve them interactively.
+- **Feature numbers are zero-padded to 3 digits** (e.g., `001`, `012`) with a `-MMDD` timestamp suffix — ensures consistent sorting and prevents collisions when multiple sessions run concurrently.
+
+## Handling Vague Inputs
+
+When the user's feature description is vague:
+1. Extract what IS clear and write that into the spec
+2. Mark genuinely ambiguous parts with `[NEEDS CLARIFICATION]` and include a recommended default
+3. Suggest running `/prizmkit-clarify` to resolve ambiguities interactively before proceeding to plan
+
+The goal is to never block progress — always produce a usable spec, even if it has open questions.
+
+## Example
+
+**Input:** "I want users to upload avatars"
+
+**Output:** `.prizmkit/specs/003-user-avatar/spec.md`
+```markdown
+# Feature: User Avatar Upload
+
+## Overview
+Allow users to upload and manage profile avatar images.
+
+## User Stories
+
+### US-1: Upload Avatar
+As a registered user, I want to upload a profile picture,
+so that other users can visually identify me.
+
+**Acceptance Criteria:**
+- Given I am on my profile page
+- When I select an image file and click upload
+- Then my avatar is updated and visible across the platform
+
+### US-2: Remove Avatar
+As a registered user, I want to remove my avatar,
+so that I can revert to a default placeholder.
+
+## Scope
+- **In scope:** Upload, display, remove avatar; image format validation
+- **Out of scope:** Image cropping/editing, avatar history
+
+## Open Questions
+- [NEEDS CLARIFICATION] Maximum file size limit? Recommended: 10MB
+```
 
-**HANDOFF:** `prizmkit.plan` or `prizmkit.clarify`
+**HANDOFF:** `/prizmkit-plan` or `/prizmkit-clarify`
 
 ## Template