prizmkit 1.1.8 → 1.1.10

package/bundled/dev-pipeline/templates/bootstrap-tier2.md

@@ -39,7 +39,9 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 ## ⚠️ Context Budget Rules (CRITICAL — read before any phase)
 
-You are running in headless mode with a FINITE context window. Exceeding it will crash the session and lose all work. Follow these rules strictly:
+You are running in **headless non-interactive mode** with a FINITE context window. Exceeding it will crash the session and lose all work. Follow these rules strictly:
+
+0. **NON-INTERACTIVE MODE** — There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input, NEVER use interactive prompts (e.g. "Would you like me to…"). If a skill has an interactive step (e.g. offer remediation, ask for approval), skip it and proceed autonomously. Make decisions based on the data available and move forward.
 
 1. **context-snapshot.md is your single source of truth** — After Phase 1 builds it, ALWAYS read context-snapshot.md instead of re-reading individual source files
 2. **Never re-read your own writes** — After you create/modify a file, do NOT read it back to verify. Trust your write was correct.
@@ -167,7 +169,7 @@ Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", mode=
 Prompt:
 > "Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
-> 2. Run prizmkit-analyze: cross-check `plan.md` (including Tasks section) against feature description and acceptance criteria for consistency.
+> 2. Cross-check `plan.md` (including Tasks section) against feature description and acceptance criteria for consistency.
 > 3. Before flagging CRITICAL or HIGH issues, read the relevant source files listed in the File Manifest to verify.
 > Report: CRITICAL, HIGH, MEDIUM issues found (or 'No issues found')."
 
@@ -262,28 +264,28 @@ Spawn Reviewer subagent (Agent tool, subagent_type="prizm-dev-team-reviewer", ru
 
 Prompt:
 > "Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
-> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
->    - Section 3: Prizm Context (RULES, PATTERNS to check against)
->    - Section 4: File Manifest (original file structure)
->    - '## Implementation Log': what Dev changed, key decisions, discoveries
-> 2. Run prizmkit-code-review (both phases): Phase 1 diagnostic review (spec compliance, code quality, correctness), then Phase 2 fix strategy formulation for any findings. Read ONLY files listed in Implementation Log for diagnosis; MAY read additional files for impact analysis.
-> 3. Run the full test suite using `{{TEST_CMD}}` — **ONLY if the Implementation Log does not already confirm all tests passing**. If the log states tests passed, trust it and skip the re-run. When running: `{{TEST_CMD}} 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep the file for details — do NOT re-run the suite multiple times. Write and execute integration tests covering all user stories.
-> 4. Write structured '## Review Notes' to context-snapshot.md with Fix Instructions (Root Cause, Impact, Fix Strategy, Code Guidance, Verification for each finding) and Re-Review Expectations.
-> Report verdict: PASS, PASS_WITH_WARNINGS, or NEEDS_FIXES."
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/spec.md` for goals and acceptance criteria
+> 2. Read `.prizmkit/specs/{{FEATURE_SLUG}}/plan.md` for architecture decisions and completed tasks
+> 3. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for RULES, PATTERNS, TRAPS
+> 4. Run /prizmkit-code-review with artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/: Phase 1 diagnostic review across all applicable dimensions, then Phase 2 fix strategy formulation for any findings. Read ONLY files referenced in completed plan.md tasks for diagnosis; MAY read additional files for impact analysis.
+> 5. Run the full test suite using `{{TEST_CMD}}`. When running: `{{TEST_CMD}} 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep the file for details — do NOT re-run the suite multiple times. Write and execute integration tests covering all goals.
+> 6. review-report.md will be written to .prizmkit/specs/{{FEATURE_SLUG}}/ by prizmkit-code-review.
+> Report: number of findings found, or 'no findings' if clean."
 
 Wait for Reviewer to return.
 
-**Gate Check — Review Notes**:
-After Reviewer agent returns, verify the Review Notes were written:
+**Gate Check — Review Report**:
+After Reviewer agent returns, verify the review report was written:
 ```bash
-grep -q "## Review Notes" .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md && echo "GATE:PASS" || echo "GATE:MISSING"
+grep -q "## Findings" .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
 ```
-If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '## Review Notes' section to context-snapshot.md with structured Fix Instructions. Include: verdict, findings with Root Cause/Impact/Fix Strategy/Code Guidance/Verification, and Re-Review Expectations."
+If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write review-report.md to .prizmkit/specs/{{FEATURE_SLUG}}/ with findings."
+
+**Verdict decision** (L4 responsibility): Read review-report.md findings count. If findings exist → NEEDS_FIXES. If no findings → PASS.
 
-- If NEEDS_FIXES: spawn Dev to fix (Dev reads Fix Instructions in snapshot), re-run Review (max 3 rounds)
+- If NEEDS_FIXES: spawn Dev to fix (Dev reads Fix Instructions in review-report.md), re-run Review (max 3 rounds)
 
-**CP-3**: Tests pass, verdict is not NEEDS_FIXES.
+**CP-3**: Tests pass, no unresolved findings.
 
 {{IF_BROWSER_INTERACTION}}
 ### Phase 5.5: Browser Verification (playwright-cli) — MANDATORY
@@ -329,7 +331,7 @@ You just implemented this feature — you know the project's tech stack and buil
 3. **Assess and record** — append to context-snapshot.md:
    - **ALL builds pass** → `## Deploy Verification: PASS` — proceed to commit
    - **Some builds fail with fixable errors** → fix and re-verify (already handled in step 2)
-   - **Cannot build locally** (missing system-level deps you cannot install) → Generate `DEPLOY.md` with:
+   - **Cannot build locally** (missing system-level deps you cannot install) → Generate `.prizmkit/deploy.md` with:
      ```
      # Local Development Setup
 
@@ -345,7 +347,7 @@ You just implemented this feature — you know the project's tech stack and buil
      ## Verify
      [how to confirm the app is running correctly]
      ```
-     Record: `## Deploy Verification: PARTIAL — see DEPLOY.md for missing prerequisites`
+     Record: `## Deploy Verification: PARTIAL — see .prizmkit/deploy.md for missing prerequisites`
 
 Deploy verification does NOT block the commit, but you MUST attempt it.
 
@@ -386,6 +388,28 @@ Working tree MUST be clean after this step. If any feature-related files remain,
 
 **Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
 
+**6e.** Write completion summary for downstream dependency context:
+
+Write `.prizmkit/specs/{{FEATURE_SLUG}}/completion-summary.json` with the key changes from this session. This file is NOT committed to git — the pipeline runner reads it to propagate context to dependent features.
+
+```json
+{
+  "completion_notes": [
+    "<each item: one key change, API, model, or integration point that downstream features may need>",
+    "Example: Added User model (id, email, password_hash, display_name) in prisma/schema.prisma",
+    "Example: POST /api/auth/register and POST /api/auth/login endpoints in src/api/auth.ts",
+    "Example: Auth middleware in src/middleware/auth.ts — validates JWT on protected routes"
+  ]
+}
+```
+
+Rules for writing completion notes:
+- Focus on **what downstream features need to know**: new APIs, models, exported functions, key file paths
+- Each note should be self-contained and concise (one line, under 120 characters preferred)
+- Include 3-8 notes covering the most important changes
+- Do NOT include test files, config changes, or internal implementation details unless they affect other features
+- If this feature has no downstream dependents, still write the summary (it serves as documentation)
+
 ## Critical Paths
 
 | Resource | Path |

package/bundled/dev-pipeline/templates/bootstrap-tier3.md

@@ -39,7 +39,9 @@ You are the **session orchestrator**. Implement Feature {{FEATURE_ID}}: "{{FEATU
 
 ## ⚠️ Context Budget Rules (CRITICAL — read before any phase)
 
-You are running in headless mode with a FINITE context window. Exceeding it will crash the session and lose all work. Follow these rules strictly:
+You are running in **headless non-interactive mode** with a FINITE context window. Exceeding it will crash the session and lose all work. Follow these rules strictly:
+
+0. **NON-INTERACTIVE MODE** — There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input, NEVER use interactive prompts (e.g. "Would you like me to…"). If a skill has an interactive step (e.g. offer remediation, ask for approval), skip it and proceed autonomously. Make decisions based on the data available and move forward.
 
 1. **context-snapshot.md is your single source of truth** — After Phase 1-2 builds it, ALWAYS read context-snapshot.md instead of re-reading individual source files
 2. **Never re-read your own writes** — After you create/modify a file, do NOT read it back to verify. Trust your write was correct.
@@ -204,7 +206,7 @@ Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", mode=
 Prompt:
 > "Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
 > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST — Section 3 has project context, Section 4 has file manifest.
-> 2. Run prizmkit-analyze: cross-check `spec.md` and `plan.md` (including Tasks section) for consistency.
+> 2. Cross-check `spec.md` and `plan.md` (including Tasks section) for consistency.
 > 3. Before flagging CRITICAL or HIGH issues, read the relevant source files listed in the File Manifest to verify.
 > Report: CRITICAL, HIGH, MEDIUM issues found (or 'No issues found')."
 
@@ -337,36 +339,35 @@ Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_i
 
 Prompt:
 > "Read {{REVIEWER_SUBAGENT_PATH}}. For feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}):
-> **IMPORTANT**: Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` FIRST.
-> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md`:
->    - Section 3: Prizm Context (RULES, PATTERNS to check against)
->    - Section 4: File Manifest (original file structure)
->    - '## Implementation Log': what Dev changed, key decisions, discoveries
-> 2. Run prizmkit-code-review (both phases): Phase 1 diagnostic review (spec compliance, code quality, correctness), then Phase 2 fix strategy formulation for any findings. Read ONLY files listed in Implementation Log for diagnosis; MAY read additional files for impact analysis.
-> 3. Run the full test suite using `{{TEST_CMD}}` — **ONLY if the Implementation Log does not already confirm all tests passing**. If Implementation Log states tests passed, trust it and skip the re-run. When running tests: `{{TEST_CMD}} 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep `/tmp/review-test-out.txt` for details — do NOT re-run the suite multiple times. Write and execute integration tests covering all user stories from spec.md.
-> 4. Write structured '## Review Notes' to context-snapshot.md with Fix Instructions (Root Cause, Impact, Fix Strategy, Code Guidance, Verification for each finding) and Re-Review Expectations.
-> Report verdict: PASS, PASS_WITH_WARNINGS, or NEEDS_FIXES."
+> 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/spec.md` for goals and acceptance criteria
+> 2. Read `.prizmkit/specs/{{FEATURE_SLUG}}/plan.md` for architecture decisions and completed tasks
+> 3. Read `.prizm-docs/root.prizm` and relevant L1/L2 docs for RULES, PATTERNS, TRAPS
+> 4. Run /prizmkit-code-review with artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/: Phase 1 diagnostic review across all applicable dimensions, then Phase 2 fix strategy formulation for any findings. Read ONLY files referenced in completed plan.md tasks for diagnosis; MAY read additional files for impact analysis.
+> 5. Run the full test suite using `{{TEST_CMD}}`. When running tests: `{{TEST_CMD}} 2>&1 | tee /tmp/review-test-out.txt | tail -20`, then grep `/tmp/review-test-out.txt` for details — do NOT re-run the suite multiple times. Write and execute integration tests covering all goals from spec.md.
+> 6. review-report.md will be written to .prizmkit/specs/{{FEATURE_SLUG}}/ by prizmkit-code-review.
+> Report: number of findings found, or 'no findings' if clean."
 
 Wait for Reviewer to return.
 
-**Gate Check — Review Notes**:
-After Reviewer agent returns, verify the Review Notes were written:
+**Gate Check — Review Report**:
+After Reviewer agent returns, verify the review report was written:
 ```bash
-grep -q "## Review Notes" .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md && echo "GATE:PASS" || echo "GATE:MISSING"
+grep -q "## Findings" .prizmkit/specs/{{FEATURE_SLUG}}/review-report.md && echo "GATE:PASS" || echo "GATE:MISSING"
 ```
-If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write the '## Review Notes' section to context-snapshot.md with structured Fix Instructions. Include: verdict, findings with Root Cause/Impact/Fix Strategy/Code Guidance/Verification, and Re-Review Expectations."
+If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write review-report.md to .prizmkit/specs/{{FEATURE_SLUG}}/ with findings."
+
+**Verdict decision** (L4 responsibility): Read review-report.md findings count. If findings exist → NEEDS_FIXES. If no findings → PASS.
 
 - If NEEDS_FIXES: spawn Dev to fix with this prompt:
-  > "Read {{DEV_SUBAGENT_PATH}}. Fix NEEDS_FIXES issues for feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
-  > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — '## Review Notes' section contains structured Fix Instructions with exact steps.
-  > 2. Follow Fix Instructions in order (respect Depends On / Blocks dependencies). Each FIX-N has: Root Cause, Fix Strategy, Code Guidance, and Verification criteria.
-  > 3. After each fix, run the Verification command listed in that FIX-N to confirm it works.
+  > "Read {{DEV_SUBAGENT_PATH}}. Fix issues for feature {{FEATURE_ID}} (slug: {{FEATURE_SLUG}}).
+  > 1. Read `.prizmkit/specs/{{FEATURE_SLUG}}/review-report.md` — contains structured Fix Instructions with exact steps.
+  > 2. Follow Fix Instructions in order (respect Depends On / Blocks dependencies). Each finding has: Root Cause, Fix Strategy, Code Guidance, and Verification criteria.
+  > 3. After each fix, run the Verification command listed in that finding to confirm it works.
   > 4. Run `{{TEST_CMD}}` to verify no regressions.
-  > 5. Append fix summary to '## Implementation Log' in context-snapshot.md.
-  > 6. Do NOT execute any git commands."
+  > 5. Do NOT execute any git commands."
   Then re-run Review (max 3 rounds).
 
-**CP-3**: Integration tests pass, verdict is not NEEDS_FIXES.
+**CP-3**: Integration tests pass, no unresolved findings.
 
 {{IF_BROWSER_INTERACTION}}
 ### Phase 5.5: Browser Verification (playwright-cli) — MANDATORY
@@ -412,7 +413,7 @@ You just implemented this feature — you know the project's tech stack and buil
 3. **Assess and record** — append to context-snapshot.md:
    - **ALL builds pass** → `## Deploy Verification: PASS` — proceed to commit
    - **Some builds fail with fixable errors** → fix and re-verify (already handled in step 2)
-   - **Cannot build locally** (missing system-level deps you cannot install) → Generate `DEPLOY.md` with:
+   - **Cannot build locally** (missing system-level deps you cannot install) → Generate `.prizmkit/deploy.md` with:
      ```
      # Local Development Setup
 
@@ -428,7 +429,7 @@ You just implemented this feature — you know the project's tech stack and buil
      ## Verify
      [how to confirm the app is running correctly]
      ```
-     Record: `## Deploy Verification: PARTIAL — see DEPLOY.md for missing prerequisites`
+     Record: `## Deploy Verification: PARTIAL — see .prizmkit/deploy.md for missing prerequisites`
 
 Deploy verification does NOT block the commit, but you MUST attempt it.
 
@@ -442,7 +443,12 @@ If the project cannot be started locally (e.g., requires external services, data
 
 ### Phase 6: Retrospective & Commit (SINGLE COMMIT) — DO NOT SKIP
 
-**For bug fixes**: run `/prizmkit-retrospective` for structural sync only (skip knowledge injection unless a new TRAPS was discovered). Use `fix(<scope>):` commit prefix.
+**Bug Fix Documentation Policy**:
+- DEFAULT: Run `/prizmkit-retrospective` with structural sync only (update file counts, interfaces, dependencies). Skip knowledge injection.
+- UPDATE DOCS (run full retrospective — Job 1 + Job 2) when bug fix causes: interface signature changes, dependency additions/removals, observable behavior changes to existing features, or newly discovered TRAPs.
+- Simple bugs: No new spec.md/plan.md needed. Use fast path.
+- Complex bugs (multi-module, cascading): Use `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/<BUG_ID>/`.
+- Commit prefix: `fix(<scope>):` (not `feat:`).
 
 **6a.** Check if feature already committed:
 ```bash
@@ -457,7 +463,7 @@ git log --oneline | grep "{{FEATURE_ID}}" | head -3
 - **L2 coverage check**: For any module/sub-module with source files created or significantly modified in this session but no L2 `.prizm` doc — evaluate whether L2 is warranted and create if so. The current session has the best context for accurate KEY_FILES, TRAPS, and DECISIONS.
 - Stage doc changes: `git add .prizm-docs/`
 ⚠️ Do NOT commit here. Only stage.
-- **For bug-fix sessions**: structural sync only, skip knowledge injection unless a genuinely new pitfall was discovered
+- **For bug-fix sessions**: structural sync (Job 1) by default. Run knowledge injection (Job 2) when the fix causes interface signature changes, dependency additions/removals, observable behavior changes, or reveals new TRAPs
 
 **6c.** Stage all feature code explicitly (NEVER use `git add -A` or `git add .`):
 ```bash
@@ -479,6 +485,28 @@ Working tree MUST be clean after this step. If any feature-related files remain,
 
 **Exception**: `session-summary.md` in the artifact directory is a local cross-session artifact generated by `/prizmkit-committer` — it is NOT committed to git. Ignore it in the clean-tree check.
 
+**6f.** Write completion summary for downstream dependency context:
+
+Write `.prizmkit/specs/{{FEATURE_SLUG}}/completion-summary.json` with the key changes from this session. This file is NOT committed to git — the pipeline runner reads it to propagate context to dependent features.
+
+```json
+{
+  "completion_notes": [
+    "<each item: one key change, API, model, or integration point that downstream features may need>",
+    "Example: Added User model (id, email, password_hash, display_name) in prisma/schema.prisma",
+    "Example: POST /api/auth/register and POST /api/auth/login endpoints in src/api/auth.ts",
+    "Example: Auth middleware in src/middleware/auth.ts — validates JWT on protected routes"
+  ]
+}
+```
+
+Rules for writing completion notes:
+- Focus on **what downstream features need to know**: new APIs, models, exported functions, key file paths
+- Each note should be self-contained and concise (one line, under 120 characters preferred)
+- Include 3-8 notes covering the most important changes
+- Do NOT include test files, config changes, or internal implementation details unless they affect other features
+- If this feature has no downstream dependents, still write the summary (it serves as documentation)
+
 ## Critical Paths
 
 | Resource | Path |

package/bundled/dev-pipeline/templates/bug-fix-list-schema.json

@@ -71,12 +71,11 @@
           "priority": {
             "type": "string",
             "enum": [
-              "critical",
               "high",
               "medium",
               "low"
             ],
-            "description": "Fix priority. Pipeline processes critical before high before medium before low; within same level, array order determines sequence."
+            "description": "Fix priority. Pipeline processes high before medium before low; within same level, array order determines sequence. Both critical and high severity map to high priority."
           },
           "error_source": {
             "type": "object",
@@ -120,11 +119,6 @@
               }
             }
           },
-          "affected_feature": {
-            "type": "string",
-            "pattern": "^F-\\d{3}(-[A-Z])?$",
-            "description": "Related original Feature ID (if any), for TRAPS cross-reference"
-          },
           "affected_modules": {
             "type": "array",
             "items": {
@@ -171,16 +165,13 @@
             "type": "string",
             "enum": [
               "pending",
-              "triaging",
-              "reproducing",
-              "fixing",
-              "verifying",
+              "in_progress",
               "completed",
               "failed",
-              "needs_info",
-              "skipped"
+              "skipped",
+              "needs_info"
             ],
-            "description": "Bug fix status, maps to pipeline phases"
+            "description": "Bug fix status. Subset of feature status enum plus needs_info."
           },
           "critic": {
             "type": "boolean",

package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md

@@ -18,12 +18,19 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
 
 **CRITICAL SESSION LIFECYCLE RULE**: You MUST NOT exit until ALL work is complete and session-status.json is written. When you spawn subagents, you MUST **wait for each to finish** (run_in_background=false) before proceeding. Do NOT spawn an agent in the background and exit — that kills the session.
 
+**NON-INTERACTIVE MODE**: You are running in headless non-interactive mode. There is NO human on the other end. NEVER ask for user confirmation, NEVER wait for user input, NEVER use interactive prompts (e.g. "Would you like me to…"). If a skill has an interactive step (e.g. offer remediation, ask for approval), skip it and proceed autonomously. Make decisions based on the data available and move forward.
+
 **MANDATORY TEAM REQUIREMENT**: You MUST use the `prizm-dev-team` agents (Dev + Reviewer). This is NON-NEGOTIABLE. All implementation and review work MUST be performed by the appropriate team agents (Dev, Reviewer). You are the orchestrator — handle coordination, planning, and commit phases directly.
 
-**BUG FIX DOCUMENTATION POLICY**: Bug fixes MUST NOT be recorded as new documentation entries:
-- Run `/prizmkit-retrospective` with structural sync only (Job 1) — skip knowledge injection unless a genuinely new TRAP was discovered
-- Do NOT create spec/plan/tasks under `.prizmkit/specs/`
-- Do NOT update `.prizm-docs/` module docs for pure bug fixes (unless TRAPS update is needed)
+**BUG FIX DOCUMENTATION POLICY**:
+- **DEFAULT**: Run `/prizmkit-retrospective` with structural sync only (Job 1). Skip knowledge injection (Job 2).
+- **UPDATE DOCS** (run full retrospective — Job 1 + Job 2) when the bug fix causes:
+  • Interface signature changes
+  • Dependency additions/removals
+  • Observable behavior changes to existing features
+  • Newly discovered TRAPs (gotchas/pitfalls)
+- **Simple bugs** (single file, clear root cause, ≤10 lines): Direct triage → fix → commit. No spec/plan needed. Artifacts: `fix-plan.md` + `fix-report.md` only.
+- **Complex bugs** (cross-module, cascading, data model/API changes): Use `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/` → generates `spec.md` + `plan.md`. Then use `/prizmkit-implement` to execute the plan. Artifacts: `spec.md` + `plan.md` + `fix-report.md`.
 - Commit with `fix(<scope>):` prefix, NOT `feat:`
 
 ### Team Definition Reference
@@ -43,10 +50,6 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
 
 {{ACCEPTANCE_CRITERIA}}
 
-### Affected Feature
-
-{{AFFECTED_FEATURE}}
-
 ### Environment
 
 {{ENVIRONMENT}}
@@ -60,12 +63,19 @@ You are the **bug fix session orchestrator**. Fix Bug {{BUG_ID}}: "{{BUG_TITLE}}
 **ALWAYS** use per-bug subdirectory `.prizmkit/bugfix/{{BUG_ID}}/`:
 
 ```
+Simple bugs:
 .prizmkit/bugfix/{{BUG_ID}}/
 ├── fix-plan.md       ← Phase 1 output (generated after triage)
 └── fix-report.md     ← Phase 5 output (generated after commit)
+
+Complex bugs (cross-module, data model/API changes):
+.prizmkit/bugfix/{{BUG_ID}}/
+├── spec.md           ← /prizmkit-plan output (goals, root cause, scope)
+├── plan.md           ← /prizmkit-plan output (fix approach, tasks)
+└── fix-report.md     ← Phase 5 output (generated after commit)
 ```
 
-**IMPORTANT**: Only 2 artifact files per bug, NEVER more. This is a fixed convention.
+**IMPORTANT**: Simple bugs produce 2 artifact files (fix-plan.md + fix-report.md). Complex bugs produce 3 artifact files (spec.md + plan.md + fix-report.md).
 
 ## Workflow Checkpoint System
 
@@ -189,18 +199,15 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
 
 - Spawn Reviewer agent (Agent tool, subagent_type="prizm-dev-team-reviewer", run_in_background=false)
   Prompt: "Read {{REVIEWER_SUBAGENT_PATH}}. For bug {{BUG_ID}}:
-  1. Run `/prizmkit-code-review` scoped to CHANGED FILES ONLY (both phases: diagnostic + fix strategy)
-  2. Review dimensions (adjusted for bug fix):
-     - Fix correctness: Does it address the root cause?
-     - Regression safety: Does it break existing behavior?
-     - Code quality: Is the fix clean and maintainable?
-     - Test coverage: Is the reproduction test adequate?
-  3. Run full test suite and verify ALL tests pass
-  4. If findings exist, produce Fix Instructions with Root Cause, Impact, Fix Strategy, Code Guidance, and Verification criteria
-  5. Report verdict: PASS / PASS_WITH_WARNINGS / NEEDS_FIXES
+  1. Read `.prizmkit/bugfix/{{BUG_ID}}/fix-plan.md` for goals, root cause, and fix approach (always exists for both simple and complex bugs)
+  2. Read `.prizmkit/bugfix/{{BUG_ID}}/plan.md` (if it exists, complex bugs only) for architecture decisions and completed tasks
+  3. Run `/prizmkit-code-review` with artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/ scoped to CHANGED FILES ONLY (both phases: diagnostic + fix strategy)
+  4. Run full test suite and verify ALL tests pass
+  5. review-report.md will be written to .prizmkit/bugfix/{{BUG_ID}}/ by prizmkit-code-review
+  6. Report: number of findings found, or 'no findings' if clean
   "
 - **Wait for Reviewer to return**
-- If NEEDS_FIXES: return to Phase 3 for refinement following Fix Instructions (max 2 review rounds)
+- **Verdict decision** (L4 responsibility): If findings exist → return to Phase 3 for refinement (max 2 review rounds). If no findings → proceed.
 - **CP-BF-4**: Code review passes, all tests green
 - **Checkpoint update**: set step `prizmkit-code-review` to `"completed"` in `{{CHECKPOINT_PATH}}`
 
@@ -224,18 +231,21 @@ Reference `{{TEAM_CONFIG_PATH}}` for agent definitions:
    - Update the affected module's TRAPS section in `.prizm-docs/`
    - Format: `- TRAP: <description> | FIX: <solution> | DATE: YYYY-MM-DD`
 
-2. Run `/prizmkit-committer` with:
+2. Run `/prizmkit-retrospective` following the BUG FIX DOCUMENTATION POLICY above:
+   - **DEFAULT**: Structural sync only (Job 1)
+   - **Full retrospective** (Job 1 + Job 2): Only if the fix changes interfaces, dependencies, observable behavior, or reveals new TRAPs
+
+3. Run `/prizmkit-committer` with:
    - Commit message: `fix({{FIX_SCOPE}}): {{BUG_TITLE}}`
    - Include both fix code and reproduction test
-   - Do NOT run `/prizmkit-retrospective` with REGISTRY archiving
    - Do NOT push (user will push manually)
 
-3. Write the complete fix report to `.prizmkit/bugfix/{{BUG_ID}}/fix-report.md`
+4. Write the complete fix report to `.prizmkit/bugfix/{{BUG_ID}}/fix-report.md`
 
   The fix-report.md MUST contain these sections:
   - Bug Resolution Summary (ID, title, status, phases completed, duration)
   - What Was Fixed (changes made, diff summary, commit message)
-  - Verification Results (reproduction test before/after, regression tests, review verdict)
+  - Verification Results (reproduction test before/after, regression tests, review findings)
   - Knowledge Captured (TRAPS updated, prevention recommendation)
   - Acceptance Criteria Verification (checklist with pass/fail for each criterion)
 
@@ -289,8 +299,9 @@ Write to: `{{SESSION_STATUS_PATH}}`
 
 - **MANDATORY**: Use `prizm-dev-team` agents — single-agent execution is FORBIDDEN
 - **Only 2 artifact files per bug**: fix-plan.md + fix-report.md — NEVER more
-- **Do NOT create** spec.md or plan.md for bug fixes
-- **Do NOT run** `/prizmkit-retrospective` knowledge injection for bugs (structural sync only, unless genuinely new TRAP discovered)
+- **Simple bugs**: No spec/plan needed — artifacts are `fix-plan.md` + `fix-report.md` only
+- **Complex bugs** (cross-module, data model/API changes): Use `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/{{BUG_ID}}/` → `spec.md` + `plan.md` + `fix-report.md`
+- **DEFAULT**: Run `/prizmkit-retrospective` structural sync only (Job 1). Run full retrospective (Job 1 + Job 2) when fix changes interfaces, dependencies, observable behavior, or reveals new TRAPs
 - **Commit with** `fix(<scope>):` prefix, NOT `feat:`
 - **Update TRAPS** in `.prizm-docs/` only if a genuinely new pitfall was discovered
 - Dev agents use TDD approach: reproduction test goes from RED → GREEN

package/bundled/dev-pipeline/templates/feature-list-schema.json

@@ -27,9 +27,6 @@
     "created_by": {
       "type": "string"
     },
-    "source_spec": {
-      "type": "string"
-    },
     "features": {
       "type": "array",
       "minItems": 1,
@@ -47,15 +44,18 @@
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^F-\\d{3}(-[A-Z])?$"
+            "pattern": "^F-\\d{3}(-[A-Z])?$",
+            "description": "Feature ID, format F-001, F-002... Optional sub-feature suffix: F-001-A"
           },
           "title": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "description": "Feature title — brief description of the functionality"
           },
           "description": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "description": "Detailed feature description: what it does, why it's needed"
           },
           "priority": {
             "type": "string",
@@ -73,21 +73,24 @@
               "low",
               "medium",
               "high"
-            ]
+            ],
+            "description": "Estimated implementation complexity. Determines pipeline execution tier: low=lite, medium=standard, high=full."
           },
           "dependencies": {
             "type": "array",
             "items": {
               "type": "string",
               "pattern": "^F-\\d{3}(-[A-Z])?$"
-            }
+            },
+            "description": "IDs of features that must be completed before this one"
           },
           "acceptance_criteria": {
             "type": "array",
             "minItems": 1,
             "items": {
               "type": "string"
-            }
+            },
+            "description": "Conditions that must be met for the feature to be considered complete"
           },
           "status": {
             "type": "string",
@@ -99,7 +102,8 @@
               "skipped",
               "split",
               "auto_skipped"
-            ]
+            ],
+            "description": "Feature status. Pipeline manages status transitions automatically."
           },
           "session_granularity": {
             "type": "string",
@@ -108,7 +112,8 @@
               "sub_feature",
               "auto"
             ],
-            "default": "feature"
+            "default": "feature",
+            "description": "Session execution strategy: feature=one-session-per-feature, sub_feature=one-session-per-sub-feature, auto=pipeline-decides"
           },
           "sub_features": {
             "type": "array",
@@ -152,6 +157,13 @@
               3
             ]
           },
+          "completion_notes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "AI-generated summary of key changes from this feature session. Used to provide rich dependency context to downstream features. Each item is a concise statement about what was built/changed (e.g. APIs added, models created, key file paths)."
+          },
           "browser_interaction": {
             "type": "object",
             "description": "Browser verification config for features with UI. Requires playwright-cli. Pipeline uses this to verify UI behavior after implementation.",