prizmkit 1.1.10 → 1.1.12

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

@@ -3,8 +3,7 @@
 ## Session Context
 
 - **Feature ID**: {{FEATURE_ID}} | **Session**: {{SESSION_ID}} | **Run**: {{RUN_ID}}
-- **Complexity**: {{COMPLEXITY}} | **Retry**: {{RETRY_COUNT}} / {{MAX_RETRIES}}
-- **Previous Status**: {{PREV_SESSION_STATUS}} | **Resume From**: {{RESUME_PHASE}}
+- **Complexity**: {{COMPLEXITY}}
 - **Init**: {{INIT_DONE}} | Artifacts: spec={{HAS_SPEC}} plan={{HAS_PLAN}}
 
 ## Your Mission
@@ -47,7 +46,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 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.
 3. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — In Phase 3 (implement), complete and test one task before starting the next.
-5. **Minimize tool output** — When running commands, use `| head -20` or `| tail -20` to limit output. Never dump entire test suites or logs.
+5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-3. All changes are committed once at the end in Phase 4 via `/prizmkit-committer`.
 7. **Capture test output once** — When running test suites, always use `$TEST_CMD 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
 
@@ -74,22 +73,8 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 ### Phase 0: SKIP (already initialized)
 {{END_IF_INIT_DONE}}
 
-{{IF_RESUME}}
-### Resume from Phase {{RESUME_PHASE}}
-Check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if it exists, skip Phase 1 and use it directly.
-{{END_IF_RESUME}}
-
 ### Phase 1: Build Context Snapshot
 
-**Check for previous failure log:**
-```bash
-cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
-```
-If failure-log.md exists:
-- Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
-- Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during Phase 4 retrospective
-- Do NOT delete failure-log.md until this session completes all phases and commits successfully
-
 ```bash
 ls .prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md 2>/dev/null && echo "EXISTS" || echo "MISSING"
 ```
@@ -118,8 +103,9 @@ If MISSING — build it now:
 ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
 ```
 
-If plan.md missing, write it directly:
-- `plan.md`: key components, data flow, files to create/modify, and a Tasks section with `[ ]` checkboxes (each task = one implementable unit). Keep under 80 lines.
+If plan.md missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate `plan.md`:
+- The plan.md should include: key components, data flow, files to create/modify, and a Tasks section with `[ ]` checkboxes (each task = one implementable unit). Keep under 80 lines.
+- Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input.
 
 **Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
 Before proceeding past CP-1:
@@ -160,31 +146,39 @@ $TEST_CMD 2>&1 | tee /tmp/test-baseline.txt | tail -20
 1. All tasks in plan.md are `[x]`
 2. Run the full test suite to ensure nothing is broken
 3. Verify each acceptance criterion from Section 1 of context-snapshot.md is met — check mentally, do NOT re-read files you already wrote
-4. If any criterion is not met, fix it now (max 2 fix rounds)
+4. If any criterion is not met, fix it now using the convergence-based recovery loop below
 
 **CP-2**: All acceptance criteria met, all tests pass.
 
 ### Test Failure Recovery Protocol
 
-When tests fail during Phase 3:
+When tests fail during Phase 3, use **convergence-based recovery** — keep fixing as long as progress is being made.
 
-1. **Analyze failure output**:
-   - Identify root cause (code bug vs. test brittleness vs. environment issue)
-   - Check if baseline already recorded this failure
+**Recovery Loop**:
 
-2. **Categorize and fix** (max 2 rounds):
-   - **Pre-existing baseline failure**: Expected, record as acceptable
-   - **New regression**: Fix the code and re-run tests
-   - **Brittle test**: Fix the test or environment
-   - **Environment issue**: Fix setup and re-run
+1. **Run tests and record results**: count total failures, note which tests failed. Exclude pre-existing baseline failures.
 
-3. **Recovery limit**:
-   - Max 2 fix attempts per failing test
-   - After 2 rounds, if still failing: document in Implementation Log with root cause
-   - **Do NOT block commit** if unable to resolve
+2. **Check termination conditions** (evaluate BEFORE each fix attempt):
+   - **All tests pass** → Done. Exit recovery loop.
+   - **Plateau detected** — same failure count AND same failing tests for 3 consecutive rounds → AI cannot resolve. Document and exit.
+   - **Still making progress** — failure count decreased vs. previous round → Continue fixing.
+   - **First round** — no history yet → Proceed to fix.
 
-4. **Failure documentation**:
-   - Test name, root cause, category, fix attempted, final status
+3. **Fix and iterate**: analyze remaining failures, apply fix, re-run `$TEST_CMD`, go back to step 1.
+
+**Convergence tracking example**:
+```
+Round 1: 5 failures [test_a, test_b, test_c, test_d, test_e]
+Round 2: 3 failures [test_b, test_d, test_e]          ← progress, continue
+Round 3: 3 failures [test_b, test_d, test_e]          ← plateau 1/3
+Round 4: 3 failures [test_b, test_d, test_e]          ← plateau 2/3
+Round 5: 3 failures [test_b, test_d, test_e]          ← plateau 3/3 → STOP
+```
+**Key rule**: If failures decrease (even by 1), the plateau counter resets to 0.
+
+**When recovery loop exits with remaining failures**:
+   - Document in Implementation Log: test name, root cause, category, rounds attempted, plateau point
+   - **Do NOT block commit** — unresolved failures are deferred to next session
    - If any AC cannot be verified due to test failure: feature is incomplete
 
 **Context-Aware Optimization**: If Implementation Log already confirms "all tests passing," skip full suite re-run.
@@ -195,27 +189,43 @@ When tests fail during Phase 3:
 
 You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running playwright-cli.
 
-**Startup**:
-1. Check if port is already in use: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
-2. Start dev server: `{{BROWSER_SETUP_COMMAND}}`
-3. Wait for server to be ready: poll `{{BROWSER_URL}}` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-4. If the page requires authentication, use playwright-cli to register a test user and log in first
+**Step 1 — Start Dev Server**:
+
+You know this project's tech stack. Detect and start the dev server yourself:
 
-**Verification**:
-5. Use `playwright-cli snapshot` on `{{BROWSER_URL}}` to discover actual element refs, then verify these goals:
+1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
+2. Choose an available port — check what the project defaults to, or pick one that is free:
+   ```bash
+   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+3. Start the dev server in background, capture PID:
+   ```bash
+   <start-command> &
+   DEV_SERVER_PID=$!
+   ```
+4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+5. If the page requires authentication, use playwright-cli to register a test user and log in first
+
+**Step 2 — Verification**:
+
+Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
    {{BROWSER_VERIFY_STEPS}}
    Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
-6. Take a final screenshot for evidence
 
-**Cleanup (REQUIRED — you started it, you stop it)**:
-7. Stop the dev server process you started in step 2 (kill the process)
-8. Verify port is released: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+Take a final screenshot for evidence.
+
+**Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
-**Reporting**:
-9. Append results to `context-snapshot.md`:
+1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+
+**Step 4 — Reporting**:
+
+Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
-   URL: {{BROWSER_URL}}
+   URL: <actual URL used>
+   Dev Server Command: <actual command used>
    Steps executed: [list]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
@@ -234,23 +244,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 `.prizmkit/deploy.md` with:
-     ```
-     # Local Development Setup
-
-     ## Prerequisites
-     - [tool]: [install instruction]
-
-     ## Build Steps
-     1. [exact command]
-
-     ## Run / Dev Mode
-     [exact command to start the app locally]
-
-     ## Verify
-     [how to confirm the app is running correctly]
-     ```
-     Record: `## Deploy Verification: PARTIAL — see .prizmkit/deploy.md for missing prerequisites`
+   - **Cannot build locally** (missing system-level deps you cannot install) → Record: `## Deploy Verification: PARTIAL — missing system deps (see below)`
 
 Deploy verification does NOT block the commit, but you MUST attempt it.
 
@@ -262,6 +256,8 @@ Deploy verification does NOT block the commit, but you MUST attempt it.
 
 If the project cannot be started locally (e.g., requires external services, databases, credentials), skip the smoke test and note why.
 
+**Deploy documentation update** — Run `/prizmkit-deploy` ONLY if this feature introduced new infrastructure or deployment-affecting changes (new database, cache, message queue, new env vars, new build steps, changed ports/protocols). If none apply, skip `/prizmkit-deploy`.
+
 ### Phase 4: Architecture Sync & Commit (SINGLE COMMIT)
 
 **4a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):

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

@@ -3,8 +3,7 @@
 ## Session Context
 
 - **Feature ID**: {{FEATURE_ID}} | **Session**: {{SESSION_ID}} | **Run**: {{RUN_ID}}
-- **Complexity**: {{COMPLEXITY}} | **Retry**: {{RETRY_COUNT}} / {{MAX_RETRIES}}
-- **Previous Status**: {{PREV_SESSION_STATUS}} | **Resume From**: {{RESUME_PHASE}}
+- **Complexity**: {{COMPLEXITY}}
 - **Init**: {{INIT_DONE}} | Artifacts: spec={{HAS_SPEC}} plan={{HAS_PLAN}}
 
 ## Your Mission
@@ -47,7 +46,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 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.
 3. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — In Phase 4 (implement), complete and test one task before starting the next.
-5. **Minimize tool output** — When running commands, use `| head -20` or `| tail -20` to limit output. Never dump entire test suites or logs.
+5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-5. All changes are committed once at the end in Phase 6 via `/prizmkit-committer`.
 7. **Capture test output once** — When running test suites, always use `$TEST_CMD 2>&1 | tee /tmp/test-out.txt | tail -20`. Then grep `/tmp/test-out.txt` for details. Never re-run the suite just to apply a different filter.
 
@@ -85,11 +84,6 @@ If any agent times out:
 ### Phase 0: SKIP (already initialized)
 {{END_IF_INIT_DONE}}
 
-{{IF_RESUME}}
-### Resume from Phase {{RESUME_PHASE}}
-Check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if exists, skip Phase 1 and proceed to Phase {{RESUME_PHASE}}.
-{{END_IF_RESUME}}
-
 ### Phase 0.5: Detect Test Commands
 
 You know this project's tech stack. Identify ALL test commands that apply (e.g., `go test ./...`, `npm test`, `cargo test`, `pytest`, `make test`, etc.). Record them as `TEST_CMDS`. Then record baseline:
@@ -150,8 +144,9 @@ If MISSING — build it now:
 ls .prizmkit/specs/{{FEATURE_SLUG}}/plan.md 2>/dev/null
 ```
 
-If either missing, write them yourself:
+If either missing, run `/prizmkit-plan` with `artifact_dir=.prizmkit/specs/{{FEATURE_SLUG}}/` to generate missing files:
 - `plan.md`: architecture — components, interfaces, data flow, files to create/modify, testing approach, and a Tasks section with `[ ]` checkboxes ordered by dependency
+- Resolve any `[NEEDS CLARIFICATION]` markers using the feature description — do NOT pause for interactive input.
 
 **Database Design Gate** (if feature involves data persistence — new tables, schema changes, new entities):
 Before proceeding past CP-1, verify:
@@ -292,27 +287,43 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write review
 
 You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running playwright-cli.
 
-**Startup**:
-1. Check if port is already in use: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
-2. Start dev server: `{{BROWSER_SETUP_COMMAND}}`
-3. Wait for server to be ready: poll `{{BROWSER_URL}}` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-4. If the page requires authentication, use playwright-cli to register a test user and log in first
+**Step 1 — Start Dev Server**:
+
+You know this project's tech stack. Detect and start the dev server yourself:
 
-**Verification**:
-5. Use `playwright-cli snapshot` on `{{BROWSER_URL}}` to discover actual element refs, then verify these goals:
+1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
+2. Choose an available port — check what the project defaults to, or pick one that is free:
+   ```bash
+   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+3. Start the dev server in background, capture PID:
+   ```bash
+   <start-command> &
+   DEV_SERVER_PID=$!
+   ```
+4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+5. If the page requires authentication, use playwright-cli to register a test user and log in first
+
+**Step 2 — Verification**:
+
+Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
    {{BROWSER_VERIFY_STEPS}}
    Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
-6. Take a final screenshot for evidence
 
-**Cleanup (REQUIRED — you started it, you stop it)**:
-7. Stop the dev server process you started in step 2 (kill the process)
-8. Verify port is released: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+Take a final screenshot for evidence.
+
+**Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
 
-**Reporting**:
-9. Append results to `context-snapshot.md`:
+1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+
+**Step 4 — Reporting**:
+
+Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
-   URL: {{BROWSER_URL}}
+   URL: <actual URL used>
+   Dev Server Command: <actual command used>
    Steps executed: [list]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
@@ -331,23 +342,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 `.prizmkit/deploy.md` with:
-     ```
-     # Local Development Setup
-
-     ## Prerequisites
-     - [tool]: [install instruction]
-
-     ## Build Steps
-     1. [exact command]
-
-     ## Run / Dev Mode
-     [exact command to start the app locally]
-
-     ## Verify
-     [how to confirm the app is running correctly]
-     ```
-     Record: `## Deploy Verification: PARTIAL — see .prizmkit/deploy.md for missing prerequisites`
+   - **Cannot build locally** (missing system-level deps you cannot install) → Record: `## Deploy Verification: PARTIAL — missing system deps (see below)`
 
 Deploy verification does NOT block the commit, but you MUST attempt it.
 
@@ -359,6 +354,8 @@ Deploy verification does NOT block the commit, but you MUST attempt it.
 
 If the project cannot be started locally (e.g., requires external services, databases, credentials), skip the smoke test and note why.
 
+**Deploy documentation update** — Run `/prizmkit-deploy` ONLY if this feature introduced new infrastructure or deployment-affecting changes (new database, cache, message queue, new env vars, new build steps, changed ports/protocols). If none apply, skip `/prizmkit-deploy`.
+
 ### Phase 6: Architecture Sync & Commit (SINGLE COMMIT)
 
 **6a.** Run `/prizmkit-retrospective` — maintains `.prizm-docs/` (architecture index):

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

@@ -3,8 +3,7 @@
 ## Session Context
 
 - **Feature ID**: {{FEATURE_ID}} | **Session**: {{SESSION_ID}} | **Run**: {{RUN_ID}}
-- **Complexity**: {{COMPLEXITY}} | **Retry**: {{RETRY_COUNT}} / {{MAX_RETRIES}}
-- **Previous Status**: {{PREV_SESSION_STATUS}} | **Resume From**: {{RESUME_PHASE}}
+- **Complexity**: {{COMPLEXITY}}
 - **Init**: {{INIT_DONE}} | Artifacts: spec={{HAS_SPEC}} plan={{HAS_PLAN}}
 
 ## Your Mission
@@ -47,7 +46,7 @@ You are running in **headless non-interactive mode** with a FINITE context windo
 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.
 3. **Stay focused** — Do NOT explore code unrelated to this feature. No curiosity-driven reads.
 4. **One task at a time** — In Phase 4 (implement), complete and test one task before starting the next.
-5. **Minimize tool output** — When running commands, use `| head -20` or `| tail -20` to limit output. Never dump entire test suites or logs.
+5. **Minimize tool output** — Never load full command output into context. First capture to a temp file (`cmd 2>&1 | tee /tmp/out.txt | tail -20`), then scan the head/tail to identify relevant fields, and use targeted filtering (`grep`, `sed`, `awk`) to extract only the information needed for the current task. Only read the filtered result — never the raw full output.
 6. **No intermediate commits** — Do NOT run `git add`/`git commit` during Phase 1-5. All changes are committed once at the end in Phase 6 via `/prizmkit-committer`.
 7. **Batch independent operations** — Issue multiple independent `Write`/`Read` calls in a single message turn when they have no dependencies. Combine multiple `mkdir -p` into one command. Never run `npm test` twice just to apply a different grep filter — capture output to `/tmp/test-out.txt` once and grep the file.
 
@@ -111,22 +110,8 @@ python3 {{INIT_SCRIPT_PATH}} --project-root {{PROJECT_ROOT}} --feature-id {{FEAT
 ```
 {{END_IF_FRESH_START}}
 
-{{IF_RESUME}}
-### Resume from Phase {{RESUME_PHASE}}
-After team setup: check `.prizmkit/specs/{{FEATURE_SLUG}}/context-snapshot.md` — if exists, all agents MUST use it. Read existing artifacts and resume from Phase {{RESUME_PHASE}}.
-{{END_IF_RESUME}}
-
 ### Phase 1-2: Specify + Plan — Orchestrator (you)
 
-**Check for previous failure log:**
-```bash
-cat .prizmkit/specs/{{FEATURE_SLUG}}/failure-log.md 2>/dev/null || echo "NO_PREVIOUS_FAILURE"
-```
-If failure-log.md exists:
-- Read ROOT_CAUSE and SUGGESTION — adjust your approach accordingly
-- Read DISCOVERED_TRAPS — if any are genuine, inject into .prizm-docs/ during Phase 6 retrospective
-- Do NOT delete failure-log.md until this session completes all phases and commits successfully
-
 Check existing artifacts first:
 ```bash
 ls .prizmkit/specs/{{FEATURE_SLUG}}/ 2>/dev/null
@@ -374,27 +359,43 @@ If GATE:MISSING — send message to Reviewer (re-spawn if needed): "Write review
 
 You MUST execute this phase. Do NOT skip it. Do NOT mark it as completed without actually running playwright-cli.
 
-**Startup**:
-1. Check if port is already in use: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
-2. Start dev server: `{{BROWSER_SETUP_COMMAND}}`
-3. Wait for server to be ready: poll `{{BROWSER_URL}}` with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
-4. If the page requires authentication, use playwright-cli to register a test user and log in first
+**Step 1 — Start Dev Server**:
+
+You know this project's tech stack. Detect and start the dev server yourself:
+
+1. Identify the dev server start command from project config (`package.json` scripts, `Makefile`, `docker-compose.yml`, etc.)
+2. Choose an available port — check what the project defaults to, or pick one that is free:
+   ```bash
+   lsof -ti:<port> 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_FREE"
+   ```
+3. Start the dev server in background, capture PID:
+   ```bash
+   <start-command> &
+   DEV_SERVER_PID=$!
+   ```
+4. Wait for server to be ready: poll the target URL with `curl -s -o /dev/null -w "%{http_code}"` until it returns 200 or 302 (max 30 seconds, 2s interval)
+5. If the page requires authentication, use playwright-cli to register a test user and log in first
+
+**Step 2 — Verification**:
 
-**Verification**:
-5. Use `playwright-cli snapshot` on `{{BROWSER_URL}}` to discover actual element refs, then verify these goals:
+Use `playwright-cli snapshot` on the running app to discover actual element refs, then verify these goals:
    {{BROWSER_VERIFY_STEPS}}
    Decide the concrete playwright-cli actions (click, fill, assert, etc.) yourself based on the snapshot output and your knowledge of the implemented code. The goals above describe WHAT to verify — you determine HOW.
-6. Take a final screenshot for evidence
 
-**Cleanup (REQUIRED — you started it, you stop it)**:
-7. Stop the dev server process you started in step 2 (kill the process)
-8. Verify port is released: `lsof -ti:3001 | xargs kill -9 2>/dev/null || true`
+Take a final screenshot for evidence.
 
-**Reporting**:
-9. Append results to `context-snapshot.md`:
+**Step 3 — Cleanup (REQUIRED — you started it, you stop it)**:
+
+1. Kill the dev server process: `kill $DEV_SERVER_PID 2>/dev/null || true`
+2. Verify port is released: `lsof -ti:<port> | xargs kill -9 2>/dev/null || true`
+
+**Step 4 — Reporting**:
+
+Append results to `context-snapshot.md`:
    ```
    ## Browser Verification
-   URL: {{BROWSER_URL}}
+   URL: <actual URL used>
+   Dev Server Command: <actual command used>
    Steps executed: [list]
    Screenshot: [path]
    Result: PASS / FAIL (reason)
@@ -413,23 +414,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 `.prizmkit/deploy.md` with:
-     ```
-     # Local Development Setup
-
-     ## Prerequisites
-     - [tool]: [install instruction]
-
-     ## Build Steps
-     1. [exact command]
-
-     ## Run / Dev Mode
-     [exact command to start the app locally]
-
-     ## Verify
-     [how to confirm the app is running correctly]
-     ```
-     Record: `## Deploy Verification: PARTIAL — see .prizmkit/deploy.md for missing prerequisites`
+   - **Cannot build locally** (missing system-level deps you cannot install) → Record: `## Deploy Verification: PARTIAL — missing system deps (see below)`
 
 Deploy verification does NOT block the commit, but you MUST attempt it.
 
@@ -441,6 +426,8 @@ Deploy verification does NOT block the commit, but you MUST attempt it.
 
 If the project cannot be started locally (e.g., requires external services, databases, credentials), skip the smoke test and note why.
 
+**Deploy documentation update** — Run `/prizmkit-deploy` ONLY if this feature introduced new infrastructure or deployment-affecting changes (new database, cache, message queue, new env vars, new build steps, changed ports/protocols). If none apply, skip `/prizmkit-deploy`.
+
 ### Phase 6: Retrospective & Commit (SINGLE COMMIT) — DO NOT SKIP
 
 **Bug Fix Documentation Policy**: