prizmkit 1.1.8 → 1.1.10

package/bundled/skills/app-planner/SKILL.md

@@ -1,26 +1,23 @@
 ---
 name: "app-planner"
-description: "Plan a new application through interactive conversation — capture vision, tech stack, constraints, and project brief. Use this skill when users say 'plan an app', 'design a new project', 'start from scratch', 'build a new application', or discuss app-level architecture and design. For adding features to existing projects, use feature-planner instead."
+description: "Plan an application through interactive conversation — capture vision, tech stack, constraints, and project brief. Works for both new (greenfield) and existing (brownfield) projects that need app-level planning. Use this skill when users say 'plan an app', 'design a new project', 'start from scratch', 'build a new application', or discuss app-level architecture and design. Also use for existing projects that need a project brief or app-level context. For adding features to existing projects that already have a project brief, use feature-planner instead."
 ---
 
 # app planner
 
-Plan a new application from idea to actionable project context through interactive conversation:
+Plan an application from idea to actionable project context through interactive conversation. Works for both **greenfield** (new) and **brownfield** (existing) projects:
 - Vision and problem statement
-- Tech stack selection
+- Tech stack selection (or confirmation of existing stack)
 - Constraints and design direction
 - Architecture decision capture
 - Project brief accumulation (`.prizmkit/plans/project-brief.md`)
 
 This skill captures **what to build and why**. For **feature decomposition and `.prizmkit/plans/feature-list.json` generation**, hand off to `feature-planner`.
 
-For adding features to an **existing** project, use `feature-planner` directly.
+For adding features to an **existing** project that already has a project brief, use `feature-planner` directly.
 
 ## Invocation Commitment (Hard Rule)
-
-**When the user invokes `/app-planner`, you MUST execute the app-planner workflow.** You must NEVER:
-- Decide on the user's behalf that the task "doesn't need app-planner"
-- Skip app-planner to jump directly to spec/plan/implement or any other skill
+ You must NEVER:
 - Bypass the interactive phases because you judge the task to be "simple"
 
 If you believe the task is better suited for a different workflow, you MUST:
@@ -35,23 +32,16 @@ If you believe the task is better suited for a different workflow, you MUST:
 - Create project scaffolding, directories, or boilerplate
 - Run build/install/test commands (npm init, pip install, etc.)
 - Execute any implementation action beyond writing planning artifacts
-- Generate `.prizmkit/plans/feature-list.json` — that is `feature-planner`'s responsibility
 
 **Your ONLY writable outputs are:**
 1. `.prizmkit/plans/project-brief.md` (`.prizmkit/plans/` — accumulated project context brief)
-2. `.prizmkit/project-conventions.json` (project convention answers)
-3. `.prizm-docs/root.prizm` (if architecture decisions are captured — see Architecture Decision Capture section)
-   - Contains architecture decisions, tech stack rationale, and key constraints
-   - Used as input by feature-planner and other workflows
-4. Architecture decisions appended to `CLAUDE.md` / `CODEBUDDY.md` (with user consent)
-5. Draft backups in `.prizmkit/planning/`
+2. Project conventions and architecture decisions appended to `CLAUDE.md` / `CODEBUDDY.md` (with user consent)
 
 **After planning is complete**, you MUST:
 1. Present the summary of captured vision, constraints, and decisions
 2. **Ask the user explicitly** whether they want to proceed to feature decomposition
-3. If the user agrees → recommend invoking `feature-planner` to decompose into features and generate `.prizmkit/plans/feature-list.json`
-4. If the user wants to continue exploring → stay in app-planner
-5. **NEVER auto-execute** the pipeline, feature-planner, or any implementation step
+3. If the user wants to continue exploring → stay in app-planner
+4. **NEVER auto-execute** the pipeline, feature-planner, or any implementation step
 
 ## When to Use
 
@@ -60,9 +50,12 @@ Trigger this skill for requests like:
 - "Start from scratch", "Build something new", "Create a new product"
 - "Help me figure out what to build", "Brainstorm an app idea"
 - "What tech stack should I use?", "Help me choose frameworks"
+- "Create a project brief for my existing project"
+- "Help me document what this project is about"
+- "I have a codebase but no project plan yet"
 
 Do NOT use this skill when:
-- The user already has a project and wants to add features → use `feature-planner`
+- The user already has a project brief and wants to add features → use `feature-planner`
 - The user wants to run the pipeline → use `feature-pipeline-launcher`
 - The user is debugging/refactoring or wants to write source code directly
 
@@ -78,11 +71,24 @@ Do NOT use this skill when:
    - During brainstorm Phase C → also read `${SKILL_DIR}/references/red-team-checklist.md`
 
 3. **Project conventions check** — after Intent Confirmation, before brainstorm or vision work:
-   → Read `.prizmkit/project-conventions.json` if it exists
-   → Cross-reference with `${SKILL_DIR}/references/project-conventions.md` for the full question list
-   → For any convention with a `null` or missing value → batch all unanswered questions into a single prompt
-   → Save answers to `.prizmkit/project-conventions.json`
-   → If all conventions are already answered → skip silently
+   → Read `CLAUDE.md` / `CODEBUDDY.md` and check for `### Project Conventions` section
+   → If section exists and all conventions are answered → skip silently
+   → If section is missing or incomplete → ask the following conventions as a single batched prompt:
+     - **UI Display Language** (`ui_language`): Primary language for the app's UI (e.g., English, 中文, 日本語). If non-English, confirm whether ALL UI text should use that language.
+     - **Multi-Language Support** (`i18n`): Whether i18n is needed. If yes, which target languages? If enabled, note i18n infrastructure early in dependency graph.
+     - **Date/Time/Currency**: Date format (YYYY-MM-DD, MM/DD/YYYY, etc.), timezone strategy (UTC storage + local display, user-selected, server only), currency format (if applicable).
+     - **Code & Git Language**: Language for code comments and git commit messages (default: English for both).
+   → Save answers to `CLAUDE.md` / `CODEBUDDY.md` under `### Project Conventions` section (format: one bullet per convention)
+   → Example output:
+     ```markdown
+     ### Project Conventions
+     - UI language: 中文
+     - i18n: disabled
+     - Date format: YYYY-MM-DD, timezone: UTC storage + local display
+     - Currency: CNY ¥
+     - Code comments: English
+     - Git commits: English
+     ```
 
 4. **Project brief accumulation** — throughout all interactive phases:
    → Read `${SKILL_DIR}/references/project-brief-guide.md` for template and rules
@@ -93,11 +99,7 @@ Do NOT use this skill when:
 Before questions, check optional context files (never block if absent):
 - `.prizm-docs/root.prizm` (architecture/project context)
 - `.prizmkit/config.json` (existing stack preferences and detected tech stack)
-- `.prizmkit/project-conventions.json` (previously answered project conventions)
-- If `.prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure to understand the codebase layout:
-  ```bash
-  find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
-  ```
+- `CLAUDE.md` / `CODEBUDDY.md` `### Project Conventions` section (previously answered project conventions)
 
 **Tech stack auto-population from config.json:**
 - If `.prizmkit/config.json` contains a `tech_stack` object, use it to pre-fill tech assumptions.
@@ -123,13 +125,61 @@ After initial greeting, confirm the user's deliverable intent:
      - Run project conventions check first
      - Load `${SKILL_DIR}/references/brainstorm-guide.md` and follow its structured ideation process (Phases A-D)
      - Brainstorm Phase D output serves as the Vision Summary (CP-AP-2)
-     - Continue with Phase 2 (constraints — including frontend design check if applicable)
-     - At Phase 2 completion, re-ask: "Ideas are taking shape. Ready to hand off to `feature-planner` for feature decomposition?"
-     - If yes → recommend invoking `feature-planner`
-     - If no → offer to continue exploring (loop back to brainstorm or constraints), or save draft to `.prizmkit/planning/` and exit
+     - After brainstorm completes, ask: "Ideas are taking shape. Ready to hand off to `feature-planner` for feature decomposition, or continue refining?"
+     - If ready → proceed to Phase 2 (constraints + frontend design check if applicable) then handoff
+     - If not ready → continue exploring, or save draft to `.prizmkit/planning/` and exit
+     - **Checkpoints in explore mode**: CP-AP-0 (required), CP-AP-1 (required), CP-AP-2 (from brainstorm output), CP-AP-3 (only if user proceeds to Phase 2), CP-AP-4 and CP-AP-5 (only if user transitions to produce mode)
 
 3. **Session goal tracking**: Track the intent (`produce` or `explore`) throughout the session. If `explore`, always re-prompt before ending.
 
+## Project State Detection (after Intent Confirmation)
+
+Detect whether this is a **greenfield** (new) or **brownfield** (existing) project and adapt the workflow accordingly.
+
+### Detection Signals
+
+| Signal | Greenfield | Brownfield |
+|--------|-----------|------------|
+| `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / `pom.xml` | absent | present |
+| `src/` or `app/` directory with source files | absent | present |
+| `.git` with commit history | absent or initial commit only | present with history |
+| Empty or near-empty directory | yes | no |
+
+### Greenfield Behavior (default)
+
+Proceed with the standard Core Workflow — ask all questions from scratch.
+
+### Brownfield Behavior
+
+When an existing project is detected:
+
+1. **Scan project structure** to understand the codebase layout:
+   ```bash
+   find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+   ```
+
+2. **Read existing project metadata** to infer tech stack and purpose:
+   - `package.json` → name, description, dependencies, scripts
+   - `pyproject.toml` / `requirements.txt` → Python dependencies
+   - `go.mod` → Go module info
+   - `README.md` → project description and goals
+   - `.prizmkit/config.json` → previously detected tech stack
+   - `.prizm-docs/root.prizm` → existing architecture context
+
+3. **Present inferred summary** to the user:
+   > "I see this is a [framework] project using [language] with [key dependencies]. Here's what I inferred about the project: [summary]. Is this correct? Anything to add or change?"
+
+4. **Pre-fill where possible** — skip questions already answerable from the codebase:
+   - Phase 2 tech stack selection → largely pre-filled from dependencies
+   - Vision/problem statement → inferred from README or package description (user confirms)
+   - Existing features → note them as `[x]` items in project brief
+
+5. **Focus remaining questions** on what CANNOT be inferred:
+   - Target users and core value proposition
+   - Future direction and planned capabilities
+   - Non-functional requirements (performance, scale, security)
+   - Design direction (for frontend projects)
+
 ## Core Workflow
 
 Execute the planning workflow in conversation mode with mandatory checkpoints:
@@ -151,23 +201,20 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
 | Checkpoint | Artifact/State | Criteria | Phase |
 |-----------|----------------|----------|-------|
 | **CP-AP-0** | Intent Confirmed | User confirmed session goal (produce / explore) | 1 |
-| **CP-AP-1** | Conventions Checked | Project conventions loaded or asked; `.prizmkit/project-conventions.json` up to date | 1 |
-| **CP-AP-2** | Vision Summary | Goal/users/differentiators confirmed by user | 1-2 |
-| **CP-AP-3** | Frontend Design Evaluated | For frontend projects: checked for existing UI/UX design system; user was asked if missing | 2 |
-| **CP-AP-4** | Project Brief Accumulated | `.prizmkit/plans/project-brief.md` exists at `.prizmkit/plans/` with at least 3 ideas listed | 3 |
+| **CP-AP-1** | Conventions Checked | Project conventions loaded or asked; `### Project Conventions` section in `CLAUDE.md` / `CODEBUDDY.md` up to date | 1 |
+| **CP-AP-2** | Vision Summary | Goal/users/differentiators confirmed by user. For brownfield: existing purpose confirmed or refined. | 1-2 |
+| **CP-AP-3** | Frontend Design Evaluated | For frontend projects: checked for existing UI/UX design system; user was asked if missing. **Auto-pass** for backend-only or non-UI projects. | 2 |
+| **CP-AP-4** | Project Brief Accumulated | `.prizmkit/plans/project-brief.md` exists at `.prizmkit/plans/` with at least 3 ideas listed. For brownfield: already-implemented items marked `[x]` count toward this total. | 3 |
 | **CP-AP-5** | Handoff Ready | All app-level context captured; user confirmed readiness for feature decomposition | 4 |
 
 ## Architecture Decision Capture
 
 After Phase 2, if framework-shaping architecture decisions emerged during planning (tech stack, communication patterns, data model strategies — not individual feature details), read `${SKILL_DIR}/references/architecture-decisions.md` and follow the capture flow. Most sessions will NOT produce architecture decisions — only capture when genuinely impactful.
 
-**Handoff to feature-planner**: Captured architecture decisions MUST be written to `.prizm-docs/root.prizm` so that feature-planner can read them as context. This ensures all downstream planners (feature, bug, refactor) share consistent architectural understanding.
-
 **How it works**:
-1. If decisions are captured → create `.prizm-docs/root.prizm` with decision summaries
-2. Also append decisions to `CLAUDE.md` / `CODEBUDDY.md` for human reference
-3. When feature-planner is invoked, it will read `.prizm-docs/root.prizm` as prerequisite context
-4. Feature decomposition will respect captured architecture decisions (no conflicting tech choices)
+1. If decisions are captured → append to `CLAUDE.md` / `CODEBUDDY.md` under `### Architecture Decisions` section
+2. Feature-planner and other downstream skills read `CLAUDE.md` / `CODEBUDDY.md` as standard context, so they automatically receive these decisions
+3. Do NOT write directly to `.prizm-docs/root.prizm` — that file is maintained by `prizmkit-prizm-docs` and `prizmkit-retrospective`. If the project needs `.prizm-docs/`, recommend the user run `prizmkit-prizm-docs` init after planning.
 
 ## Project Brief Accumulation
 
@@ -175,26 +222,6 @@ During interactive planning, maintain a `.prizmkit/plans/project-brief.md` at `.
 
 → Read `${SKILL_DIR}/references/project-brief-guide.md` for full format and rules.
 
-**Format**: One idea per line, each starting with `[ ]`. Example:
-```
-# Project Brief
-
-[x] 表示构想已在某个 feature 中实现完成
-
---------
-
-[ ] B2B SaaS 餐饮库存管理平台，面向中小连锁餐厅
-[ ] 核心价值：通过预测性订货减少 30% 食物浪费
-[ ] 必须支持 iPad Safari 离线模式
-```
-
-**Key rules**:
-- After each meaningful user response → append a new `[ ]` line
-- One idea, one sentence per line — no paragraphs
-- Max 500 words total
-- Must have at least 3 ideas listed before CP-AP-4
-- The pipeline will mark `[x]` and append file paths when features are implemented
-
 ## Session Exit Gate
 
 Prevent accidental session exit without completing the planning artifacts.
@@ -203,8 +230,7 @@ Prevent accidental session exit without completing the planning artifacts.
 
 Activate when ALL true:
 - Session goal = `produce`
-- `.prizmkit/plans/project-brief.md` has not been written or is incomplete (Vision section missing)
-- No architecture decisions captured yet (if any emerged)
+- `.prizmkit/plans/project-brief.md` has not been written or is incomplete (fewer than 3 ideas listed)
 
 ### Gate Behavior
 
@@ -222,4 +248,4 @@ After all checkpoints pass, present a summary and recommend next steps:
 1. **Summary**: List captured vision, tech stack, constraints, architecture decisions, and project brief status
 2. **Primary recommendation**: Invoke `feature-planner` to decompose the application into features and generate `.prizmkit/plans/feature-list.json` (schema: `dev-pipeline-feature-list-v1`, uses `project_name` field for the app name)
 3. **Alternative**: If the user wants to continue refining the vision or constraints, stay in app-planner
-4. **Artifacts produced**: List files written (`.prizmkit/plans/project-brief.md`, `.prizmkit/project-conventions.json`, architecture decisions if any)
+4. **Artifacts produced**: List files written (`.prizmkit/plans/project-brief.md`, project conventions and architecture decisions in `CLAUDE.md` / `CODEBUDDY.md`)

package/bundled/skills/app-planner/assets/app-design-guide.md

@@ -42,7 +42,7 @@ Use these tables to guide tech stack selection based on project requirements.
 
 | Framework | Best For | Ecosystem |
 |-----------|----------|-----------|
-| Next.js 14+ | Full-stack React, SSR, API routes | React ecosystem, Vercel |
+| Next.js | Full-stack React, SSR, API routes | React ecosystem, Vercel |
 | Nuxt 3 | Full-stack Vue, SSR | Vue ecosystem |
 | SvelteKit | Performance-focused, smaller teams | Svelte ecosystem |
 | Remix | Nested routes, data loading | React ecosystem |

package/bundled/skills/app-planner/references/architecture-decisions.md

@@ -20,7 +20,7 @@ Only capture decisions that are **framework-shaping** — NOT individual feature
 
 ## When to Capture
 
-After Phase 5 (DAG verification), before Phase 6 (JSON generation). At this point decisions are settled.
+After Phase 2 (Confirm constraints and tech assumptions), before Phase 3 (Capture architecture decisions and finalize project brief). At this point decisions are settled.
 
 ## How to Capture
 

package/bundled/skills/app-planner/references/project-brief-guide.md

@@ -1,79 +1,82 @@
-# Project Brief — Checklist Format Guide
+# Project Brief Template
 
-> Capture the user's key product ideas as a simple checklist in `project-brief.md`. Each line is one idea. The dev-pipeline injects this file into every feature session so the AI understands the user's overall product vision.
+> Capture the user's key product ideas as a simple checklist. Each line is one idea. This file is referenced by `root.prizm` (`PROJECT_BRIEF:`) so every new AI session automatically knows the project's goals.
 
-## Purpose
+## File Location
 
-During `app-planner` conversation, the user describes what they want to build. `project-brief.md` distills these into a flat checklist — one idea per line. When `dev-pipeline` builds individual features, each session sees this checklist and understands the bigger picture.
+`.prizmkit/plans/project-brief.md`
 
-## Persistence
-
-- **File**: `project-brief.md` at `.prizmkit/plans/` (shared location with `feature-list.json`)
-- **Format**: Checklist — one idea per line, `[ ]` for pending, `[x]` for completed
-- **Size limit**: 500 words max (injected into every session's context window)
-- **Consumed by**: `dev-pipeline/scripts/generate-bootstrap-prompt.py` → `{{PROJECT_BRIEF}}` placeholder
-
-## File Format
+## Format
 
 ```markdown
 # Project Brief
 
-[x] 表示构想已在某个 feature 中实现完成
-
---------
-
-[ ] B2B SaaS 餐饮库存管理平台，面向中小连锁餐厅 (5-50 家门店)
-[ ] 核心价值：通过预测性订货减少 30% 食物浪费
-[ ] 必须支持 iPad Safari 离线模式，厨房平板 WiFi 不稳定
-[ ] 后端可部署到客户自有云（多租户但可自托管）
-[ ] RESTful API + JWT 认证，不用 GraphQL
-[ ] 使用 Supabase (PostgreSQL) 作为数据库和认证
-[ ] TailwindCSS + shadcn/ui 统一前端组件
-[ ] 所有金额用整数（分）存储，避免浮点精度问题
-[ ] Dashboard 在 3G 网络下 2 秒内加载
-[ ] 供应商集成 API 支持 webhook 回调
-[ ] 用户端中文界面，管理后台英文界面
+[ ] Core product idea or constraint
+[ ] Another product idea
+[ ] Third idea — one sentence, no sub-bullets
+[x] Already implemented feature -> src/feature/, src/utils/helper.ts
 ```
 
-## Format Rules
+## Rules
 
 1. **First line**: `# Project Brief`
-2. **Second line**: `[x] 表示构想已在某个 feature 中实现完成` — fixed legend
-3. **Third line**: `--------` — separator
-4. **Remaining lines**: One idea per line, each starting with `[ ]`
-5. Each line is **one sentence** — no paragraphs, no sub-bullets
-6. Language: match the user's language (Chinese or English)
-
-## How app-planner Writes It
-
-During interactive conversation, after each meaningful user response (skip acknowledgments, yes/no):
-- Evaluate whether the response contains a product idea, constraint, design decision, or technical preference
-- If yes → append a new `[ ]` line to `project-brief.md`
-- Keep each line concise — one idea, one sentence
-- Merge or condense if approaching 500-word limit
-
-**First write**: Create the file with the header, legend, separator, and initial ideas.
-**Subsequent writes**: Append new `[ ]` lines only — do not rewrite existing lines.
-
-## How the Pipeline Marks Completion
-
-When a feature session in `dev-pipeline` completes and its implementation addresses one or more ideas from the checklist:
-1. Change `[ ]` to `[x]` for that idea
-2. Append 1-2 key directory/file paths after the idea text, showing where it was implemented
-
-Example of a completed item:
-```
-[x] RESTful API + JWT 认证，不用 GraphQL → src/middleware/auth.ts, src/routes/api/
-```
-
-## Checkpoint
-
-Verified at **CP-AP-4**: Before handoff to `feature-planner`, `project-brief.md` must exist with at least 3 ideas listed.
-
-## How the Pipeline Uses It
-
-`generate-bootstrap-prompt.py` reads `project-brief.md` and injects its content into the `{{PROJECT_BRIEF}}` section of every bootstrap prompt (tier1/tier2/tier3). The framing:
-
-> "Product ideas checklist from planning. Lines marked [x] are already implemented. When your feature touches any [ ] item, ensure alignment. After implementation, mark relevant items [x] and append the key file paths."
+2. **Remaining lines**: One idea per line, prefixed with `[ ]` (pending) or `[x]` (done)
+3. Each line is **one sentence** — no paragraphs, no sub-bullets, no grouping headers
+4. Language: match the user's language (Chinese or English)
+5. **Size limit**: 500 words max (this file is injected into every session's context window)
+6. **Completion marking** (mandatory): When a brief item is implemented:
+   - Change `[ ]` to `[x]`
+   - Append `->` followed by the **key file or directory paths** that implement it
+   - List the most important 1-3 paths only (entry point, core module, or directory) — not every touched file
+   - Example: `[x] User authentication with OAuth -> src/auth/, src/middleware/auth.ts`
+   - This lets future AI sessions instantly locate the implementation without re-scanning
+
+## Brownfield Init
+
+When initializing an existing project, AI infers the brief from:
+- Generated `root.prizm` (tech stack, module structure)
+- `README.md` (if exists)
+- Package metadata (`package.json` description, `pyproject.toml`, etc.)
+
+Then presents the draft to the user for confirmation and editing.
+
+## Greenfield Init
+
+When initializing a new/empty project, use **progressive questioning** to fully understand the user's intent before generating the brief. Do NOT dump all questions at once — ask in rounds, adapting based on answers.
+
+### Round 1: Problem & Vision (required)
+- What problem does this project solve? (or: what's the core idea?)
+- Who is the target user / audience?
+
+### Round 2: Scope & Features (required)
+- What are the 3-5 core features or capabilities? (ask user to list them)
+- What is the MVP scope? (what's the minimum version that delivers value?)
+- Are there any explicit non-goals? (things this project deliberately does NOT do)
+
+### Round 3: Technical Constraints (if user has preferences)
+- Any preferred tech stack / language / framework?
+- Any integration requirements? (third-party APIs, databases, auth providers)
+- Deployment target? (web app, mobile, CLI, library, self-hosted, cloud)
+
+### Round 4: Clarification (adaptive — only if gaps remain)
+If previous answers are vague or incomplete, probe deeper:
+- "You mentioned X — can you give a concrete example of how a user would use it?"
+- "Are there existing tools that do something similar? How is yours different?"
+- "What does success look like for V1?"
+
+### Completion Criteria
+Stop asking when ALL of these are clear:
+1. **Problem** — what pain point or opportunity this addresses
+2. **Users** — who will use it and in what context
+3. **Core features** — at least 3 concrete capabilities (not vague aspirations)
+4. **Boundaries** — what's in scope vs. out of scope for V1
+5. **Technical direction** — enough to populate `config.json` tech_stack (or explicitly deferred)
+
+If the user gives short/vague answers, don't accept them — rephrase and ask again. A weak brief leads to weak specs downstream.
+
+### Generate & Confirm
+Once all criteria are met:
+1. Generate brief in checklist format (see Format section above)
+2. Present to user with: "Here's what I captured — anything to add, remove, or change?"
+3. Apply edits and write to `.prizmkit/plans/project-brief.md`
 
-If the file does not exist, the placeholder is replaced with `(No project brief available)`.

package/bundled/skills/bug-fix-workflow/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: "bug-fix-workflow"
-tier: companion
-description: "Interactive single-bug fix in current session. Guides through deep diagnosis Q&A → triage → reproduce → fix → review → commit without the background pipeline. Use this skill when the user wants to fix one specific bug right now, interactively. Trigger on: 'fix this bug', 'debug this', 'fix B-001', 'help me fix', 'let me fix this bug myself', 'fix this bug', 'interactive fix', 'manually fix bug'. (project)"
+description: "Interactive single-bug fix in current session. Guides through deep diagnosis Q&A → triage → reproduce → fix → review → commit without the background pipeline. Use this skill when the user wants to fix one specific bug right now, interactively. Trigger on: 'fix this bug', 'debug this', 'fix B-001', 'help me fix', 'let me fix this bug myself', 'fix this bug', 'interactive fix', 'manually fix bug'."
 ---
 
 # Bug Fix Workflow
@@ -83,7 +82,7 @@ For trivial bugs with clear root cause and minimal scope:
 
 **Goal**: Fully understand the bug before touching any code. Vague bug reports lead to incorrect fixes that mask the real issue or introduce new bugs.
 
-**Fast Path Decision Point**: After initial information gathering (Step 1.1), evaluate the Fast Path Eligibility Criteria above. If ALL criteria are met, ask the user: "This looks like a straightforward fix. Use fast path? (Y/n)". If yes, skip directly to the Fast Path Workflow (branch setup already done in Phase 0). If no or uncertain, continue with full diagnosis.
+**Fast Path Decision Point**: After initial information gathering (Step 1.1), evaluate the Fast Path Eligibility Criteria in Step 1.4. If ALL simple bug criteria are met, ask the user: "This looks like a straightforward fix. Use fast path? (Y/n)". If yes, skip directly to the Fast Path Workflow (branch setup already done in Phase 0). If no or uncertain, continue with full diagnosis.
 
 **CRITICAL RULE**: Ask as many questions as needed until the bug is fully understood. Do NOT rush into code. A misdiagnosed bug leads to a wrong fix, which is worse than no fix.
 
@@ -146,6 +145,35 @@ Ask the user: "Is this summary accurate? Any details to add?"
 
 ---
 
+#### Step 1.4: Complexity Assessment
+
+After confirming bug understanding, assess whether this bug needs structured planning:
+
+**Simple bug → Fast Path** (ALL must be true):
+- Root cause is immediately obvious (typo, missing null check, wrong variable name, off-by-one)
+- Fix is ≤10 lines of code in a single file
+- No cross-module impact
+- Existing tests cover the affected path (or bug is in untested utility)
+- No data model or API changes
+
+→ Proceed with Fast Path Workflow (Phase 0 branch already set up)
+
+**Complex bug → Planning Path** (ANY is true):
+- Cross-module impact (>2 files affected)
+- Data model or API changes required
+- Root cause is uncertain or multi-layered
+- Fix requires structural changes
+- Multiple interrelated symptoms
+
+→ Invoke `/prizmkit-plan` with `artifact_dir=.prizmkit/bugfix/<BUG_ID>/`:
+  1. prizmkit-plan generates `spec.md` + `plan.md` under `.prizmkit/bugfix/<BUG_ID>/`
+  2. Invoke `/prizmkit-implement` to execute the plan
+  3. After implementation, resume this workflow at Phase 5 (Review)
+
+Ask the user: "This bug appears [simple/complex]. Use [fast path/structured planning]? (Y/n)"
+
+---
+
 ### Phase 2: Triage
 
 **Goal**: Locate affected code, identify root cause, classify severity.
@@ -169,6 +197,8 @@ Ask the user: "Is this summary accurate? Any details to add?"
    ```
    Ask: "Does this diagnosis look right? Should I proceed with the fix?"
 
+**CHECKPOINT CP-BFW-2**: Root cause identified and diagnosis confirmed by user.
+
 ### Phase 3: Reproduce
 
 **Goal**: Create a failing test that proves the bug exists.
@@ -186,6 +216,8 @@ If the bug is hard to reproduce automatically (e.g. environment-specific):
 - Write a manual reproduction checklist instead
 - Proceed to Phase 4 with the manual checklist
 
+**CHECKPOINT CP-BFW-3**: Bug reproduction test written and confirmed failing.
+
 ### Phase 4: Fix
 
 **Goal**: Implement the minimal fix. Red test → green.
@@ -202,6 +234,8 @@ If the bug is hard to reproduce automatically (e.g. environment-specific):
    - Test results (reproduction + regression)
    - Ask: "Fix looks good? Any concerns?"
 
+**CHECKPOINT CP-BFW-4**: Fix implemented and all tests passing (reproduction + regression).
+
 If the fix causes test regressions:
 - Show which tests broke and why
 - Revise the fix (max 3 attempts)
@@ -228,6 +262,8 @@ If the fix causes test regressions:
    Ready to commit.
    ```
 
+**CHECKPOINT CP-BFW-5**: Code review completed and quality verified.
+
 ### Phase 6: User Verification
 
 **Goal**: Let the user verify the fix works as expected before committing.
@@ -244,6 +280,8 @@ If user reports the fix is NOT working:
 - Return to Phase 4 (max 2 more attempts)
 - If still failing: escalate with analysis
 
+**CHECKPOINT CP-BFW-6**: Fix manually verified by user and working as expected.
+
 ---
 
 ### Phase 7: Commit & Merge
@@ -254,7 +292,10 @@ If user reports the fix is NOT working:
    - Commit message: `fix(<scope>): <description>`
    - Include both fix code and reproduction test
    - Do NOT push (user decides when to push)
-   - Do NOT run `/prizmkit-retrospective` — bug fixes do not update `.prizm-docs/`
+   - **Bug Fix Documentation Policy**:
+     - DEFAULT: Run `/prizmkit-retrospective` with structural sync only (update file counts, interfaces, dependencies). Skip knowledge injection.
+     - UPDATE DOCS when bug fix causes: interface signature changes, dependency additions/removals, observable behavior changes to existing features, or newly discovered TRAPs (gotchas/pitfalls)
+     - When any of the above apply, run full `/prizmkit-retrospective` (Job 1 + Job 2)
    - `/prizmkit-committer` is a pure commit tool — it does NOT modify `.prizm-docs/` or any project files
 2. **Ask merge preference**:
    ```
@@ -278,6 +319,8 @@ If user reports the fix is NOT working:
    Or retry the pipeline to pick up remaining bugs.
    ```
 
+**CHECKPOINT CP-BFW-7**: Fix committed and merge decision made.
+
 ## Resume — Interruption Recovery
 
 The workflow supports resuming from the last completed phase by detecting existing artifacts.