prizmkit 1.1.164 → 1.1.165

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (24) hide show
  1. package/bundled/VERSION.json +3 -3
  2. package/bundled/skills/_metadata.json +1 -1
  3. package/bundled/skills/app-planner/SKILL.md +18 -9
  4. package/bundled/skills/app-planner/references/app-design-guide.md +7 -5
  5. package/bundled/skills/app-planner/references/brainstorm-guide.md +13 -21
  6. package/bundled/skills/app-planner/references/generated-plan-review.md +6 -2
  7. package/bundled/skills/bug-planner/SKILL.md +13 -4
  8. package/bundled/skills/bug-planner/assets/bug-confirmation-template.md +11 -7
  9. package/bundled/skills/bug-planner/references/generated-plan-review.md +7 -3
  10. package/bundled/skills/feature-planner/SKILL.md +12 -3
  11. package/bundled/skills/feature-planner/assets/planning-guide.md +13 -13
  12. package/bundled/skills/feature-planner/references/completeness-review.md +8 -4
  13. package/bundled/skills/feature-planner/references/generated-plan-review.md +6 -2
  14. package/bundled/skills/prizmkit-plan/SKILL.md +15 -4
  15. package/bundled/skills/prizmkit-plan/assets/plan-template.md +18 -3
  16. package/bundled/skills/prizmkit-plan/assets/spec-template.md +17 -5
  17. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +26 -24
  18. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +5 -2
  19. package/bundled/skills/prizmkit-plan/references/verification-checklist.md +15 -6
  20. package/bundled/skills/refactor-planner/SKILL.md +17 -8
  21. package/bundled/skills/refactor-planner/references/generated-plan-review.md +6 -2
  22. package/bundled/skills/refactor-planner/references/planning-phases.md +14 -9
  23. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +8 -2
  24. package/package.json +1 -1
@@ -1,5 +1,5 @@
1
1
  {
2
- "frameworkVersion": "1.1.164",
3
- "bundledAt": "2026-08-01T15:40:39.387Z",
4
- "bundledFrom": "1ca7c6d"
2
+ "frameworkVersion": "1.1.165",
3
+ "bundledAt": "2026-08-02T02:15:32.796Z",
4
+ "bundledFrom": "24d3678"
5
5
  }
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "1.1.164",
2
+ "version": "1.1.165",
3
3
  "skills": {
4
4
  "prizmkit": {
5
5
  "description": "Framework introduction and navigation for the formal single-requirement lifecycle, project initialization, Prizm docs, and independent deployment.",
@@ -16,6 +16,15 @@ This skill captures **project-level planning context only**: vision, tech stack,
16
16
 
17
17
  For adding features to an **existing** project that already has a project brief, use `feature-planner` directly.
18
18
 
19
+ ## Intent-Aligned Planning Policy
20
+
21
+ Before proposing or finalizing app context:
22
+ 1. Establish the **intent baseline**: confirmed goal, success outcome, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
23
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never promote an inference or recommendation into user intent.
24
+ 3. **Clarify by decision impact**. Ask before choices that materially change goals, external behavior, scope, compatibility, safety, cost, or irreversible state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption or explicit deferral instead of interrupting.
25
+ 4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful trade-offs without manufacturing an option count or applying a universal default.
26
+ 5. Produce **minimum-sufficient** app context: every decision maps to a confirmed goal, constraint, existing contract, or evidenced risk, and every goal maps to observable completion evidence for downstream work. Defer unsupported future work.
27
+
19
28
  ## Invocation Commitment (Hard Rule)
20
29
  You must NEVER:
21
30
  - Bypass the interactive phases because you judge the task to be "simple"
@@ -184,19 +193,19 @@ Note:
184
193
 
185
194
  ## Interaction Style (Hard Rule)
186
195
 
187
- **ALL decision points MUST use the `AskUserQuestion` tool** to present interactive, selectable options. Do NOT render options as plain text (e.g., `[A] option [B] option`) — the user must be able to click/select, not type a letter.
196
+ Use the `AskUserQuestion` tool for mandatory authorization gates and **consequential decision points** that materially change product intent, project constraints, architecture, compatibility, cost, safety, or an irreversible choice. Do NOT render those options as plain text (e.g., `[A] option [B] option`) — the user must be able to click/select, not type a letter.
188
197
 
189
198
  This applies to:
190
199
  - Intent confirmation
191
- - Project conventions
192
- - Tech stack selection
193
- - Architecture decisions
200
+ - Consequential project conventions, tech-stack selections, and architecture decisions not already determined by evidence
194
201
  - Session exit gates
195
- - Brownfield prerequisite check
196
- - Any other decision point
202
+ - Brownfield prerequisite checks that change the selected workflow
203
+ - Any other high-impact decision requiring user authorization
204
+
205
+ Do not turn evidence-resolvable or low-risk reversible details into mandatory decision points. Inspect project evidence first; then record a disclosed assumption or explicit deferral when safe. Existing checkpoints that explicitly require user authorization remain mandatory.
197
206
 
198
207
  **How to use `AskUserQuestion`:**
199
- - Each decision point → one `AskUserQuestion` call with 1-4 questions. Use multiple calls as needed — there is NO limit on total rounds for project-level convention discovery. Keep going until everything is covered.
208
+ - Group 1-4 related questions in one call when they share a decision context. Use another call when an earlier answer changes which later question is relevant; do not pursue rounds merely to eliminate low-impact uncertainty.
200
209
  - Each question has 2-4 selectable options (the tool auto-adds "Other" for custom input)
201
210
  - Use `multiSelect: true` when the user can pick more than one
202
211
  - Mark the recommended option first and append "(Recommended)" to its label
@@ -271,9 +280,9 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
271
280
  ### Interactive Phases
272
281
  1. Clarify business goal and scope
273
282
  1.1 Confirm deliverable intent (→ Intent Confirmation — option-based)
274
- 1.2 **Requirement clarification** — for ANY unclear aspect of the user's vision, goals, target users, or scope, use option-based questions where possible. When common patterns exist, present them as choices. Only use open-ended questions for truly unique input (e.g., "describe your app idea"). Follow up with option-based clarifications.
283
+ 1.2 **Requirement clarification** — classify uncertainty by impact. Use option-based questions for consequential ambiguity in vision, goals, target users, scope, or non-goals; resolve evidence-backed facts from project context and record low-risk reversible assumptions without mandatory questioning. Use open-ended questions for genuinely unique input (e.g., "describe your app idea") and group related follow-ups.
275
284
  2. Confirm constraints and tech assumptions
276
- 2.1 Tech stack selection — use `${SKILL_DIR}/references/app-design-guide.md` §2 decision matrix. Use `AskUserQuestion` for each major tech decision (framework, database, styling, etc.)
285
+ 2.1 Tech stack selection — use `${SKILL_DIR}/references/app-design-guide.md` §2 as a comparison aid. Ask only about unresolved choices that materially affect the project; do not mechanically ask for every framework, database, or styling preference when evidence or a safe deferral already resolves it.
277
286
  2.2 **Frontend design check** (for frontend projects) — scan for existing UI/UX design docs. If none found, use `AskUserQuestion`:
278
287
  - Question: "No UI/UX design docs found. Would you like to establish design direction?"
279
288
  - Options: "Establish design direction now (Recommended)", "Skip for now", "I have external designs"
@@ -90,11 +90,13 @@ Use these tables to guide tech stack selection based on project requirements.
90
90
 
91
91
  ### Selection Heuristics
92
92
 
93
- - If the user has no strong preference, default to **Next.js + PostgreSQL + shadcn/ui + Tailwind CSS** as a general-purpose stack.
94
- - If the project involves ML/AI backends, prefer **FastAPI** on the backend.
95
- - If the project requires high concurrency with minimal resource usage, consider **Go**.
96
- - If rapid prototyping is the goal, consider **SQLite** initially with a migration path to PostgreSQL.
97
- - Always ask about deployment preferences (Vercel, AWS, self-hosted) as this influences framework choice.
93
+ Treat the matrices as comparison aids, not a universal stack prescription:
94
+
95
+ - Preserve an existing supported stack unless confirmed goals or evidence justify migration.
96
+ - When the user has no strong preference, compare only options that fit the product outcome, team capability, delivery horizon, deployment environment, operational ownership, and verified project conventions. Recommend one with explicit rationale; do not apply a universal default stack.
97
+ - Consider FastAPI for an ML/AI backend, Go for evidenced high-concurrency/resource constraints, or SQLite for a bounded prototype only when those conditions are confirmed and the trade-offs fit the intent.
98
+ - Ask about deployment when it materially constrains framework, data, cost, compliance, or operations. Otherwise record deployment as explicitly deferred rather than forcing a premature decision.
99
+ - Keep recommendations distinct from confirmed user decisions and state what evidence change would cause the recommendation to be reconsidered.
98
100
 
99
101
 
100
102
 
@@ -15,8 +15,7 @@ Evaluate the user's initial goal statement:
15
15
  - **Vague** — Direction exists but needs narrowing (e.g., "improve security")
16
16
  - **Exploring** — No firm goal yet, just a direction (e.g., "something with auth")
17
17
 
18
- If **vague** or **exploring**, ask follow-up questions to sharpen the goal.
19
- Do NOT proceed until there is a concrete, testable problem statement (one sentence).
18
+ If **vague** or **exploring**, ask about ambiguity that changes the problem, beneficiary, success outcome, or scope. Resolve evidence-backed facts from available context and disclose low-risk assumptions. Do not proceed until there is a concrete, testable problem statement, but do not interrogate implementation details that are not needed to define the problem.
20
19
 
21
20
  ### Phase B: Understand the Idea
22
21
 
@@ -27,20 +26,13 @@ Answer these questions (use codebase exploration as needed):
27
26
  3. **What exists today?** — Current state, prior art in the codebase, adjacent systems.
28
27
  4. **What constraints matter?** — Performance, compatibility, security, timeline.
29
28
 
30
- Non-functional requirements to explicitly clarify or propose defaults for:
31
- - Performance expectations
32
- - Scale (users, data, traffic)
33
- - Security or privacy constraints
34
- - Reliability / availability needs
35
- - Maintenance and ownership expectations
29
+ Consider non-functional dimensions only when they materially affect the app decision: performance, scale, security/privacy, reliability, maintenance, ownership, cost, or another domain-specific constraint. Use project evidence first. If a relevant low-risk value remains unknown, propose and clearly mark a reversible **assumption**; if different answers materially change the product or architecture, ask the user.
36
30
 
37
- If the user is unsure on any point, propose reasonable defaults and clearly mark them as **assumptions**.
38
-
39
- Summarize findings before moving on. If anything is unclear, ask.
31
+ Summarize confirmed facts, evidence-backed inferences, recommendations, assumptions, and consequential unknowns before moving on.
40
32
 
41
33
  ### Phase C: Explore Approaches
42
34
 
43
- Generate **2-3 distinct approaches**. For each:
35
+ First determine whether materially different viable paths exist. If they do, generate the smallest useful comparison—usually 2-3 approaches, but never manufacture options to satisfy a count. If one evidence-supported path remains, explain why alternatives are not materially viable and proceed with that path. For each compared approach:
44
36
 
45
37
  - **Name** — Short label (e.g., "JWT middleware", "OAuth proxy")
46
38
  - **How it works** — 2-3 sentences
@@ -59,9 +51,9 @@ Before asking the user to choose, stress-test each approach using the red team c
59
51
  4. Who disagrees?
60
52
 
61
53
  Mark any approach that fails 2+ red team questions as **HIGH RISK**.
62
- If all approaches fail, generate a hybrid addressing the weaknesses.
54
+ If every viable approach is high risk, reconsider the problem or generate a hybrid that addresses the evidenced weaknesses.
63
55
 
64
- Present the comparison and let the user pick an approach or request a hybrid.
56
+ Present only meaningful choices. Ask the user to select when the choice materially affects product intent, architecture, cost, compatibility, or another consequential outcome; otherwise record the evidence-supported recommendation as a disclosed, reversible assumption.
65
57
 
66
58
  ### Phase D: Capture Design
67
59
 
@@ -72,7 +64,7 @@ Produce a structured summary:
72
64
  [One sentence, testable]
73
65
 
74
66
  ## Approaches Considered
75
- [2-3 approaches with pros/cons/effort]
67
+ [Material alternatives with pros/cons/effort, or why only one viable path remained]
76
68
 
77
69
  ## Selected Approach
78
70
  [Complete selected approach and rationale, written as standalone design context without answer tokens or dialogue provenance]
@@ -93,9 +85,9 @@ This summary becomes the input for the next phase (specification or planning).
93
85
 
94
86
  ## Rules
95
87
 
96
- - Ask as many questions as needed — no rushing
97
- - One topic at a time for complex clarifications
98
- - Prefer multiple-choice questions when possible
99
- - Assumptions must be explicit, never silent
100
- - YAGNI ruthlessly — avoid premature complexity
101
- - Do NOT implement, code, or modify behavior during brainstorming
88
+ - Clarify consequential uncertainty; do not ask merely to remove every unknown.
89
+ - Group related questions when one answer does not depend on another; sequence only dependent decisions.
90
+ - Prefer selectable options for material choices when possible.
91
+ - Keep confirmed facts, inferences, recommendations, assumptions, and unknowns distinct.
92
+ - Apply YAGNI ruthlessly: every selected design element must map to the intent baseline, a confirmed constraint, an existing contract, or an evidenced risk.
93
+ - Do NOT implement, code, or modify behavior during brainstorming.
@@ -40,6 +40,9 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
40
40
 
41
41
  For every reviewed app-planning artifact or section, check:
42
42
 
43
+ - Intent fidelity and constraint precedence: the selected product outcome, success meaning, scope, non-goals, and project constraints preserve confirmed user intent rather than AI preferences or generic best practices
44
+ - Evidence status honesty: confirmed facts, evidence-backed inferences, recommendations, assumptions, deferrals, and unknowns remain distinct; no consequential project decision is silently defaulted
45
+ - Design necessity and traceability: every app-level decision maps to a confirmed goal, constraint, existing contract, or evidenced risk, and unsupported future complexity is absent
43
46
  - Project brief completeness: goal, users, differentiators, constraints, tech stack assumptions, and at least three actionable ideas when producing a final brief
44
47
  - Consistency among conventions, infrastructure, architecture decisions, and project brief content
45
48
  - Infrastructure completeness or explicit deferral for database, deployment, and cloud services topics when those flows ran
@@ -57,14 +60,15 @@ For every reviewed app-planning artifact or section, check:
57
60
 
58
61
  Repeat the pre-generation simulation for every reviewed new or changed app-planning line or section as if the reviewer has never seen the planning conversation. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
59
62
 
60
- 1. What exact product outcome or technical decision does this content record?
61
- 2. What exists today and what desired state or constraint applies?
63
+ 1. What exact confirmed product outcome or technical decision does this content record, and how does it preserve the intent baseline?
64
+ 2. What exists today, which statements are facts versus assumptions/recommendations, and what desired state or constraint applies?
62
65
  3. Which approach was selected, expressed by meaning rather than an option label?
63
66
  4. What constraints and non-goals must downstream work preserve?
64
67
  5. Why is each reference material relevant?
65
68
  6. How will downstream planning or implementation know the decision was honored?
66
69
  7. Does any phrase require an unseen earlier question, recommendation, or option list?
67
70
  8. Do quoted source materials agree with the final task decision?
71
+ 9. Is every included decision necessary for a confirmed goal, constraint, existing contract, or evidenced risk, with no speculative future design?
68
72
 
69
73
  Return `NEEDS_FIXES` if any answer is missing, ambiguous, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Ask the user for clarification when there is not one provable antecedent. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content into the durable artifact, which must not depend on that source file still existing.
70
74
 
@@ -7,6 +7,15 @@ description: "Interactive bug planning that produces, validates, appends, and su
7
7
 
8
8
  Interactive planning skill that creates, updates, validates, and summarizes the standardized `.prizmkit/plans/bug-fix-list.json` for later autonomous bug-fix execution. It never fixes source code.
9
9
 
10
+ ## Intent-Aligned Planning Policy
11
+
12
+ Before proposing or finalizing bug contracts:
13
+ 1. Establish the **intent baseline**: confirmed actual behavior, expected outcome, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
14
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never present a suspected root cause, code location, or fix approach as confirmed user intent.
15
+ 3. **Clarify by decision impact**. Ask before choices that materially change expected behavior, scope, compatibility, safety, severity, verification, cost, or irreversible state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
16
+ 4. Explore alternatives only when **materially different viable paths** affect the behavioral contract. Compare meaningful trade-offs without manufacturing an option count or prescribing an unverified fix.
17
+ 5. Produce a **minimum-sufficient** bug contract: every requirement maps to confirmed behavior, a constraint, existing contract, or evidenced risk, and every expected outcome maps to observable completion evidence. Defer speculative cleanup and unsupported future work.
18
+
10
19
  ## Invocation Commitment (Hard Rule)
11
20
 
12
21
  When the user invokes `/bug-planner`, you MUST execute the bug-planner workflow. You must NEVER:
@@ -47,7 +56,7 @@ Every new or changed bug is an executable contract for a fresh AI session that h
47
56
  1. **Self-contained contract**: The bug's `description` and `acceptance_criteria`, read together, MUST define the objective, current state and actual behavior, desired state and expected behavior, selected scope and decisions, severity rationale, constraints, non-goals, relevant integrations, edge cases, reproduction conditions, verification decisions, and completion evidence. Because no separate rationale field is added, include the durable severity rationale in `description`. Preserve user requirements at matching detail.
48
57
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. Logs, stack traces, screenshots, and source excerpts may support diagnosis, but they MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh bug-fix session must still know what fails, where and when it fails, what correct behavior means, which scope was selected, and how to verify the fix.
49
58
  3. **Severity and verification are durable decisions**: Write the complete severity rationale, selected scope, environment, reproduction path, verification type, and verification decisions by meaning. Never store only an option label or conversational answer.
50
- 4. **Clarify, do not guess**: Ask the user for clarification whenever expected behavior, root-cause scope, material applicability, or a relative reference has multiple plausible meanings.
59
+ 4. **Clarify by impact, do not guess**: Expected behavior, selected behavioral scope, material applicability, and relative references require clarification when multiple meanings would materially change the contract. Root cause, code location, and fix approach may remain explicitly labeled as evidence-backed hypotheses or unknowns when the confirmed behavior and bounded investigation path are sufficient for execution.
51
60
  5. **Bug isolation**: Each bug contract and its supplementary evidence contain only material relevant to that bug. Repeat shared environment or constraints only when explicitly global.
52
61
 
53
62
  ### Artifact-Wide AI Readability
@@ -191,7 +200,7 @@ Gather project metadata from the project's own configuration and documentation
191
200
  - Auto-detect from project files (`package.json`, `requirements.txt`, `go.mod`, etc.)
192
201
  - If none found, ask the user
193
202
  3. **Identify testing framework**: Read from `.prizmkit/config.json` `tech_stack.testing`, or auto-detect from package.json/requirements.txt/etc., or ask user
194
- 4. **Clarify context** — if the project context, affected systems, or bug scope is unclear, ask questions one at a time (cite the unclear point, give a recommended answer with rationale) until you fully understand the environment. No limit on rounds or number of questions.
203
+ 4. **Clarify context by impact** — inspect project evidence first. Ask when ambiguity in the environment, affected systems, expected behavior, or scope would materially alter the bug contract; label recommendations as recommendations and group related questions unless one answer changes the next. Record low-risk reversible assumptions explicitly instead of questioning until subjective full understanding.
195
204
  5. **Collect reference materials** — **Upfront Material Detection (Hard Rule)**: If the user has already provided materials (file paths, URLs, rules, specifications, code snippets) in the same message that invoked this skill: (a) Acknowledge what was received: "I received the following materials: [list]"; (b) Read/fetch all provided materials immediately; (c) You MUST still ask: "Are there any additional materials you'd like to provide?"; (d) NEVER skip this collection step just because the user already provided some materials.
196
205
 
197
206
  If the user has NOT provided any materials upfront, explicitly ask whether they have any supplementary materials for you to review before proceeding to bug collection:
@@ -229,7 +238,7 @@ When parsing user input, auto-detect the format and read `${SKILL_DIR}/reference
229
238
  - Acceptance criteria (auto-suggest based on description, user can edit)
230
239
  - Model override (optional; if specified, overrides $MODEL env var for this bug fix)
231
240
 
232
- **Per-bug clarification** — if the bug's root cause, reproduction steps, current/actual behavior, desired/expected behavior, selected scope, severity rationale, verification decisions, non-goals, integration impact, edge cases, or evidence purpose is unclear, ask focused questions one at a time (cite the unclear point, give a recommended answer with rationale) until the bug is fully understood. Do not finalize shorthand that requires an unseen question, recommendation, or option list. No limit on the number of questions per bug.
241
+ **Per-bug clarification** — require confirmed current/actual behavior, desired/expected behavior, consequential scope, severity rationale, and verification decisions. Inspect evidence before asking, group related consequential questions, and label any root cause, code location, integration impact, or fix direction as confirmed, evidence-backed hypothesis, or unknown. A fresh execution session may investigate an unknown root cause; do not force certainty or invent a fix merely to finish planning. Do not finalize shorthand that requires an unseen question, recommendation, or option list.
233
242
 
234
243
  **Per-bug confirmation (mandatory)** — after extracting and clarifying each bug, present a structured summary using the template in `${SKILL_DIR}/assets/bug-confirmation-template.md`, then ask the three confirmation questions defined there.
235
244
 
@@ -288,7 +297,7 @@ Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available onl
288
297
  - Description clearly states **expected** vs **actual** behavior (not just "X doesn't work")
289
298
  - Reproduction path is specific enough for the pipeline AI to locate the relevant code
290
299
  - If the bug involves user interaction, the trigger action is described (not just the symptom)
291
- - **Code location hints**: Where in the codebase should the AI look? (file paths, module names, function names)
300
+ - **Code location guidance**: Provide evidence-backed file/module/function hints when known; otherwise state the bounded discovery target and mark the exact location unknown rather than inventing one
292
301
  - **Verification method**: How should the AI verify the fix? (run specific test, check specific behavior)
293
302
  - Bad: "Login is broken" — too vague, AI will search the entire codebase
294
303
  - Good: "Login form at /login returns 500 when password field is empty. Expected: validation error 400. Root cause likely in src/api/auth.ts POST /api/auth/login handler — missing null check on password field."
@@ -10,22 +10,26 @@ Present this after extracting and clarifying each bug:
10
10
  │ Description: <expected vs actual behavior>
11
11
  │ Severity: <auto-classified> | Verification: <type>
12
12
  │
13
- │ Reproduction: <steps if available, or "not provided">
14
- │ Affected: <module/feature or "unknown">
13
+ │ Reproduction: <confirmed steps/evidence, or "unknown — bounded discovery required">
14
+ │ Affected: <evidence-backed module/feature, or "unknown">
15
+ │ Root Cause: <confirmed / evidence-backed hypothesis / unknown> — <basis or investigation boundary>
15
16
  │
16
17
  │ Acceptance Criteria (fix verified when):
17
18
  │ 1. <criterion — specific enough for automated pipeline to verify>
18
19
  │ 2. <criterion>
19
20
  │
20
- │ Open Questions:
21
- │ - <any unclear points, or "None">
21
+ │ Evidence Status:
22
+ │ - Confirmed facts: <actual/expected behavior and evidence>
23
+ │ - Hypotheses/assumptions: <clearly labeled, or "None">
24
+ │ Open Consequential Questions:
25
+ │ - <decisions that materially change behavior/scope/verification, or "None">
22
26
  └────────────────────────────────────────────────────────
23
27
  ```
24
28
 
25
29
  Then ask three confirmation questions:
26
- 1. "Is the description accurate? Any corrections?"
27
- 2. "Need to add more details? (reproduction steps, environment, related code locations, etc.)"
28
- 3. "Are the acceptance criteria specific enough that the pipeline can autonomously verify the fix?"
30
+ 1. "Are the confirmed actual behavior, expected behavior, and selected scope accurate?"
31
+ 2. "Are the evidence, hypotheses, unknowns, and severity rationale labeled correctly?"
32
+ 3. "Are the acceptance criteria specific enough that the pipeline can autonomously verify the outcome without assuming a particular unproven fix?"
29
33
 
30
34
  Only finalize the bug entry after user confirms all three points.
31
35
 
@@ -29,6 +29,9 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
29
29
 
30
30
  For every reviewed bug entry, check:
31
31
 
32
+ - Intent fidelity: confirmed actual behavior, expected outcome, behavioral scope, non-goals, and verification preserve the user's meaning rather than an AI-selected fix
33
+ - Evidence status honesty: facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; suspected root causes, code locations, and fix approaches are never presented as confirmed without evidence
34
+ - Minimum-sufficient scope: every requested change maps to confirmed behavior, an existing contract, constraint, or evidenced risk; speculative cleanup and unsupported future work are absent
32
35
  - Schema compatibility with `dev-pipeline-bug-fix-list-v1` and `.prizmkit/dev-pipeline/templates/bug-fix-list-schema.json`
33
36
  - Dependency/DAG consistency, duplicate handling, and root-cause overlap
34
37
  - Description completeness: objective, current/actual behavior, desired/expected behavior, selected scope, reproduction path, code-location hints, affected environment, relevant integrations, constraints, non-goals, edge cases, verification decisions, completion evidence, and headless execution readiness
@@ -45,14 +48,15 @@ For every reviewed bug entry, check:
45
48
 
46
49
  Repeat the pre-generation simulation for every reviewed new or changed bug as if the reviewer has never seen the planning conversation. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
47
50
 
48
- 1. What exact problem or outcome is this task responsible for?
49
- 2. What exists today and what must change from actual to expected behavior?
50
- 3. Which fix scope and verification approach were selected, expressed by meaning rather than an option label?
51
+ 1. What exact confirmed problem or outcome is this task responsible for?
52
+ 2. What exists today, what must change from actual to expected behavior, and which statements are confirmed versus hypothesized?
53
+ 3. Which behavioral fix scope and verification approach were selected, expressed by meaning rather than an option label, without prescribing an unproven implementation?
51
54
  4. What constraints and non-goals must be preserved?
52
55
  5. Why is each reference material relevant?
53
56
  6. How can completion be verified?
54
57
  7. Does any phrase require an unseen earlier question, recommendation, or option list?
55
58
  8. Do quoted source materials agree with the final task decision?
59
+ 9. Is every requested change necessary for confirmed behavior, a constraint, existing contract, or evidenced risk, with no speculative cleanup?
56
60
 
57
61
  Return `NEEDS_FIXES` if any answer is missing, ambiguous, available only in `user_context`, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable bug contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content and evidence excerpt into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
58
62
 
@@ -13,6 +13,15 @@ Always produce a validated `.prizmkit/plans/feature-list.json` that conforms to
13
13
 
14
14
  For planning a **new application from scratch** (vision, tech stack, decomposition), use `app-planner` instead.
15
15
 
16
+ ## Intent-Aligned Planning Policy
17
+
18
+ Before proposing or finalizing feature contracts:
19
+ 1. Establish the **intent baseline**: confirmed product goal, success outcome, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
20
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never promote an inference or preferred implementation into user intent.
21
+ 3. **Clarify by decision impact**. Ask before choices that materially change product behavior, scope, compatibility, safety, cost, or irreversible state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
22
+ 4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful trade-offs without manufacturing an option count or applying a universal default.
23
+ 5. Produce a **minimum-sufficient** feature contract: every requirement maps to a confirmed goal, constraint, existing contract, or evidenced risk, and every goal maps to observable completion evidence. Defer speculative features and unsupported future infrastructure.
24
+
16
25
  ## Invocation Commitment (Hard Rule)
17
26
 
18
27
  **When the user invokes `/feature-planner`, you MUST execute the feature-planner workflow.** You must NEVER:
@@ -54,7 +63,7 @@ Every new or changed feature is an executable contract for a fresh AI session th
54
63
 
55
64
  1. **Self-contained contract**: The feature's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired state, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence. Preserve detailed user requirements at matching detail; normalization must not simplify substantive rules.
56
65
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may preserve scoped source excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract in `description` and `acceptance_criteria`. If `user_context` were removed, a fresh execution session must still know exactly what to implement and how to prove completion.
57
- 3. **Clarify, do not guess**: Ask the user for clarification whenever requirements conflict or a reference has multiple plausible antecedents. Do not finalize the feature while ambiguity remains.
66
+ 3. **Clarify by impact, do not guess**: Ask when conflicting requirements or multiple plausible antecedents would materially change product behavior, scope, compatibility, safety, cost, or completion evidence. Resolve evidence-backed facts from project context and retain safe low-risk reversible choices as explicit assumptions rather than silently inventing user intent.
58
67
  4. **Feature isolation**: In multi-feature planning, each contract and its supplementary evidence contain only material relevant to that feature. Repeat shared context only when it explicitly applies to every affected feature. Ask the user to map material whose applicability is unclear.
59
68
 
60
69
  ### Artifact-Wide AI Readability
@@ -272,7 +281,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
272
281
 
273
282
  ### Interactive Phases
274
283
  1. Clarify scope and goals
275
- 1.1 **Requirement clarification** — for ANY unclear aspect of the user's goals or scope, ask questions one at a time (cite the unclear point, give a recommended answer with rationale) until you fully understand. No limit on rounds. Do not proceed to Phase 2 with unresolved ambiguities.
284
+ 1.1 **Requirement clarification** — establish the intent baseline, inspect project evidence, and classify uncertainty by decision impact. Ask about consequential ambiguity in goals, external behavior, scope, non-goals, compatibility, safety, cost, or irreversible choices; label recommendations and group related questions unless answers are dependent. Proceed when consequential ambiguity is resolved and any low-risk reversible assumptions are explicit—not when every unknown has been eliminated.
276
285
  1.2 **Collect reference materials** — **Upfront Material Detection (Hard Rule)**: If the user has already provided materials (file paths, URLs, rules, specifications, code snippets) in the same message that invoked this skill: (a) Acknowledge what was received: "I received the following materials: [list]"; (b) Read/fetch all provided materials immediately; (c) You MUST still ask: "Are there any additional materials you'd like to provide?"; (d) NEVER skip this collection step just because the user already provided some materials.
277
286
 
278
287
  If the user has NOT provided any materials upfront, explicitly ask whether they have any supplementary materials for you to review. Present this as a single prompt covering all material types:
@@ -289,7 +298,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
289
298
  2. Confirm constraints and existing architecture
290
299
  3. Propose feature set with dependencies
291
300
  4. Refine descriptions and acceptance criteria
292
- 4.1 **Per-feature clarification** — for each feature, if the description, acceptance criteria, selected decision, scope, non-goals, edge cases, integration points, completion evidence, or material purpose is vague or could be interpreted multiple ways, ask the user to clarify before finalizing. Reject conversational shorthand that requires an unseen question, recommendation, or option list.
301
+ 4.1 **Per-feature clarification** — for each feature, ask when multiple interpretations of behavior, acceptance criteria, scope, non-goals, material integrations, or completion evidence would materially change the contract. Resolve evidence-backed details from project context, label low-risk reversible assumptions, and reject conversational shorthand that requires an unseen question, recommendation, or option list. Do not force user confirmation for unconstrained implementation details that a fresh session can safely decide and verify.
293
302
  4.2 **Browser interaction** (mandatory for fullstack/frontend projects) — see §Browser Interaction Planning below. Qualifying features get `browser_interaction` by default. Only confirm with the user as a batch summary; do NOT ask per-feature.
294
303
  5. Verify DAG/order/priorities and show the mandatory priority/complexity calibration table with short rationales for every item
295
304
  6. Run the pre-generation Headless Context Completeness Gate (see §Pre-Generation Completeness Review below)
@@ -8,7 +8,7 @@ For app-level design references (vision templates, tech stack matrix), see `app-
8
8
 
9
9
  ## Feature Description Writing Guide
10
10
 
11
- Feature descriptions are the **primary input** for autonomous pipeline sessions. A thin description forces the AI to guess — producing worse code. Invest in rich descriptions upfront.
11
+ Feature descriptions are the **primary input** for autonomous pipeline sessions. A thin description forces the AI to guess, while an overprescribed description can turn assumptions into requirements. Write the minimum-sufficient contract: preserve every confirmed behavior and constraint at matching detail, and omit unsupported implementation choices or unrelated future design.
12
12
 
13
13
  ### Minimum Word Counts
14
14
 
@@ -21,17 +21,17 @@ Feature descriptions are the **primary input** for autonomous pipeline sessions.
21
21
 
22
22
  Below 15 words is a validation error. Below the recommended minimum triggers a warning.
23
23
 
24
- **There is NO upper limit** — the more detail the better. Rich descriptions prevent the AI from guessing, producing higher quality code. Always aim to describe the feature as thoroughly as possible: what to build, how it should behave, what data it touches, and what edge cases to handle.
24
+ There is no schema-level upper limit, but length is not a quality target. Add detail only when it establishes confirmed intent, current/desired behavior, constraints, integrations, relevant edge cases, or completion evidence. Do not add speculative infrastructure, API shape, data fields, or future capability merely to reach a recommended word count.
25
25
 
26
26
  ### What to Include
27
27
 
28
- Every description should cover these aspects (adapt per feature type):
28
+ Cover only the aspects that are material to this feature; omit non-applicable dimensions rather than inventing content:
29
29
 
30
- 1. **What to build** — concrete deliverables (API endpoints, UI pages/components, CLI commands, data models)
31
- 2. **Key behaviors** — business rules, validation, state transitions, workflows
32
- 3. **Integration points** — which existing modules, services, or APIs it connects to
33
- 4. **Data model** — entities, relationships, key fields, storage approach (when applicable)
34
- 5. **Error/edge cases** — failure modes, empty states, limits, unauthorized access
30
+ 1. **Outcome and deliverables** — confirmed user-visible or system-observable result; name endpoints, pages, commands, or models only when the contract or existing system establishes them
31
+ 2. **Key behaviors** — business rules, validation, state transitions, and workflows required by the intent
32
+ 3. **Integration points** — verified existing modules, services, APIs, or predecessor outputs and why they matter
33
+ 4. **Data model** — entities, relationships, and constraints when persistence is genuinely required
34
+ 5. **Relevant error/edge cases** — failures, empty states, limits, permissions, concurrency, or idempotency only where they affect completion
35
35
 
36
36
  ### Good vs Bad Examples
37
37
 
@@ -61,7 +61,7 @@ Feature entries are consumed by **autonomous AI sessions running in headless mod
61
61
 
62
62
  **Must include for headless readiness:**
63
63
  1. **Objective and current state** — the exact outcome and what exists today
64
- 2. **Desired state and selected decisions** — the complete chosen behavior or approach, never only an option label
64
+ 2. **Desired state and selected decisions** — the complete chosen product/contract behavior, never only an option label; include implementation approach only when the user, an existing contract, or verified project constraints actually select it
65
65
  3. **Constraints and non-goals** — boundaries the implementation must preserve
66
66
  4. **Relevant integrations** — existing APIs, models, modules, services, and dependency outputs
67
67
  5. **Edge cases** — validation, permissions, empty/error states, limits, concurrency, or idempotency when relevant
@@ -123,7 +123,7 @@ Then [expected outcome]
123
123
 
124
124
  1. **One behavior per criterion.** Each criterion tests exactly one thing.
125
125
  2. **No implementation details.** Criteria describe what, not how. Say "user is redirected" not "React Router navigates to /dashboard."
126
- 3. **Include edge cases.** Cover invalid input, unauthorized access, empty states, and error conditions.
126
+ 3. **Include relevant edge cases.** Cover invalid input, unauthorized access, empty states, and error conditions only when they can affect the confirmed outcome.
127
127
  4. **Be measurable.** Where performance matters, include specific thresholds (e.g., "within 2 seconds").
128
128
  5. **Keep the count manageable.** A feature with more than 8 acceptance criteria may need to be split into sub-features.
129
129
 
@@ -186,17 +186,17 @@ Anti-pattern: a generated plan where every item is `Priority: high` and `Complex
186
186
 
187
187
  These rules ensure the feature dependency graph is valid and buildable.
188
188
 
189
- 1. **F-001 has zero dependencies.** The first feature is always infrastructure or project setup. It must be buildable from scratch with no preconditions.
189
+ 1. **F-001 has zero feature-list dependencies.** It is the first independently executable deliverable for the current project state; make it infrastructure or setup only when confirmed prerequisites require that work. Do not recreate setup that already exists.
190
190
 
191
191
  2. **No circular dependencies.** Dependencies MUST form a directed acyclic graph (DAG). If A depends on B and B depends on A, restructure the features.
192
192
 
193
193
  3. **Minimal dependency sets.** Each feature should depend only on the features it directly needs. Do not add transitive dependencies explicitly. If F-003 depends on F-002 and F-002 depends on F-001, then F-003 does NOT need to list F-001 as a dependency.
194
194
 
195
- 4. **Auth comes early.** Most features depend on authentication. Place auth-related features (registration, login, session management) as early in the graph as possible, typically F-002.
195
+ 4. **Place authentication before its consumers when required.** Do not add or prioritize authentication merely because it is common; use the confirmed product scope and existing auth state.
196
196
 
197
197
  5. **Data model before display.** Features that create or define data entities must precede features that display, search, or manipulate that data.
198
198
 
199
- 6. **Infrastructure before everything.** Database setup, project scaffolding, CI/CD configuration, and environment setup belong in F-001.
199
+ 6. **Place missing prerequisites before their consumers.** Database, scaffolding, CI/CD, or environment work belongs early only when it is absent, in scope, and required by a confirmed feature. Existing-project planning must not manufacture infrastructure tasks.
200
200
 
201
201
  7. **Independent features can be parallel.** If two features share no dependencies on each other, they can be built in parallel. The dependency graph should reflect this by not artificially linking them.
202
202
 
@@ -12,8 +12,8 @@ Scan all AI-visible fields and sections, not only the main contract. Every gener
12
12
 
13
13
  For each new or changed feature, answer all of these from `description` and `acceptance_criteria` alone:
14
14
 
15
- 1. What exact problem or outcome is this feature responsible for?
16
- 2. What exists today and what must change?
15
+ 1. What exact confirmed problem or outcome is this feature responsible for, and how does it preserve the intent baseline?
16
+ 2. What exists today, which statements are facts versus inferences/assumptions, and what must change?
17
17
  3. Which approach was selected, expressed by meaning rather than an option label?
18
18
  4. What constraints and non-goals must be preserved?
19
19
  5. Which existing modules, APIs, data, dependencies, or other relevant integrations are involved?
@@ -22,8 +22,10 @@ For each new or changed feature, answer all of these from `description` and `acc
22
22
  8. Does any phrase require an unseen earlier question, recommendation, or option list?
23
23
  9. Why is each reference material relevant, and what should the execution AI inspect?
24
24
  10. Do quoted source materials agree with the final task decision?
25
+ 11. Does every prescribed behavior or design choice map to a confirmed goal, constraint, existing contract, or evidenced risk?
26
+ 12. Are any unresolved consequential decisions hidden behind an AI recommendation or silent default?
25
27
 
26
- If any answer is unavailable, ambiguous, or present only in `user_context`, the verdict is `NEEDS_FIXES`. Never infer a missing decision from conversation memory.
28
+ If any consequential answer is unavailable, ambiguous, or present only in `user_context`, the verdict is `NEEDS_FIXES`. A low-risk, local, reversible implementation assumption may remain when it is labeled and paired with a verification point; never infer a missing product decision from conversation memory.
27
29
 
28
30
  ## Step 2: Contract and Material Checks
29
31
 
@@ -57,7 +59,9 @@ Look at the feature set as a whole:
57
59
  - **Implied functionality gaps**: Does one feature assume a capability that no feature provides?
58
60
  - **Missing integration seams**: If two features share data or interact at runtime, is the interface specified by meaning?
59
61
  - **Dependency context**: Does each dependent feature state exactly which predecessor output it consumes?
60
- - **Scope leaks**: Does a description activate rejected or out-of-scope functionality?
62
+ - **Scope leaks**: Does a description activate rejected or out-of-scope functionality, speculative future capability, or unsupported infrastructure?
63
+ - **Design necessity**: Does every prescribed component, interface, or dependency map to confirmed intent, an existing contract, or an evidenced risk?
64
+ - **Evidence status**: Are recommendations and inferred implementation details clearly separated from confirmed product decisions?
61
65
  - **Source conflict**: Does an excerpt describe an earlier alternative that conflicts with the selected final decision?
62
66
 
63
67
  ## Step 4: Present Review and Repair
@@ -29,6 +29,9 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
29
29
 
30
30
  For every reviewed feature entry, check:
31
31
 
32
+ - Intent fidelity: confirmed product outcome, success meaning, scope, non-goals, and constraints preserve user intent rather than AI preferences or generic best practices
33
+ - Evidence status honesty: confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; no consequential product or contract decision is silently defaulted
34
+ - Minimum-sufficient design: every prescribed behavior, component, interface, or dependency maps to a confirmed goal, constraint, existing contract, or evidenced risk; speculative features and unsupported infrastructure are absent
32
35
  - Schema compatibility with `dev-pipeline-feature-list-v1` and `.prizmkit/dev-pipeline/templates/feature-list-schema.json`
33
36
  - Dependency/DAG soundness: dependencies exist, no cycles, no poorly ordered prerequisite chains
34
37
  - Description completeness and headless execution readiness: `description` plus `acceptance_criteria` defines objective, current state, desired state, selected decisions, constraints, non-goals, relevant integrations, edge cases, and completion evidence without conversation history
@@ -45,14 +48,15 @@ For every reviewed feature entry, check:
45
48
 
46
49
  Repeat the pre-generation simulation for every reviewed new or changed feature as if the reviewer has never seen the planning conversation. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
47
50
 
48
- 1. What exact problem or outcome is this task responsible for?
49
- 2. What exists today and what must change?
51
+ 1. What exact confirmed problem or outcome is this task responsible for, and how does it preserve the intent baseline?
52
+ 2. What exists today, which statements are facts versus inferences/assumptions, and what must change?
50
53
  3. Which approach was selected, expressed by meaning rather than an option label?
51
54
  4. What constraints and non-goals must be preserved?
52
55
  5. Why is each reference material relevant?
53
56
  6. How can completion be verified?
54
57
  7. Does any phrase require an unseen earlier question, recommendation, or option list?
55
58
  8. Do quoted source materials agree with the final task decision?
59
+ 9. Does every prescribed behavior or design choice have a confirmed requirement, constraint, existing contract, or evidenced risk, with no speculative future scope?
56
60
 
57
61
  Return `NEEDS_FIXES` if any answer is missing, ambiguous, available only in `user_context`, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable task contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
58
62
 
@@ -32,6 +32,15 @@ A change artifact can describe a feature, bug fix, refactor, migration, test imp
32
32
 
33
33
  `prizmkit-plan` owns specification, plan, task generation, and planning-quality review for one supplied requirement. Its terminal outputs are `PLAN_READY` or `PLAN_BLOCKED`; it stops after producing that result.
34
34
 
35
+ ## Intent-Aligned Planning Policy
36
+
37
+ Before proposing or finalizing a plan:
38
+ 1. Establish the **intent baseline**: confirmed goal, success outcome, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
39
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never promote an inference or recommendation into user intent.
40
+ 3. **Clarify by decision impact**. Ask before choices that materially change goals, external behavior, scope, compatibility, safety, cost, or irreversible state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
41
+ 4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful trade-offs without manufacturing an option count or applying a universal default.
42
+ 5. Produce a **minimum-sufficient** plan: every plan element maps to a confirmed goal, constraint, existing contract, or evidenced risk, and every goal maps to observable completion evidence. Defer unsupported future work.
43
+
35
44
  ## Phase 0: Initialization Check and Context
36
45
 
37
46
  1. Check whether project context such as `.prizmkit/prizm-docs/root.prizm`, `.prizmkit/config.json`, or a project brief exists.
@@ -49,13 +58,14 @@ Skip regeneration when `spec.md` already exists and still matches the requested
49
58
  - otherwise derive the normalized title slug, allocate the next collision-safe number, and create `.prizmkit/specs/<number>-<slug>/`.
50
59
  3. Generate `spec.md` from `${SKILL_DIR}/assets/spec-template.md`:
51
60
  - focus on WHAT and WHY, not HOW;
61
+ - record the intent baseline and evidence status without turning recommendations into requirements;
52
62
  - include only relevant sections;
53
63
  - give every goal acceptance criteria;
54
- - mark genuine ambiguity with `[NEEDS CLARIFICATION]`.
64
+ - mark consequential ambiguity with `[NEEDS CLARIFICATION]`; retain low-risk unknowns as explicit assumptions when safe.
55
65
  4. For persistence changes, inspect existing schemas and add a Data Model section using project conventions.
56
66
  5. Resolve clarification markers:
57
- - interactive: use `${SKILL_DIR}/references/clarify-guide.md` and ask targeted questions;
58
- - non-interactive: choose conservative defaults, annotate them, and block when a safe default is impossible.
67
+ - interactive: use `${SKILL_DIR}/references/clarify-guide.md`; ask about consequential decisions and record safe low-risk assumptions without silently defaulting user intent;
68
+ - non-interactive: choose conservative defaults only when they are safe and reversible, annotate them, and block when a consequential decision has no safe default.
59
69
 
60
70
  Internal ID hygiene: PrizmKit IDs, task/session/run IDs, branch names, absolute worktree paths, and internal artifact paths may exist in change artifacts but must not leak into `.prizmkit/prizm-docs/`, product UI copy, API responses, emails, notifications, or expected user-visible test strings.
61
71
 
@@ -69,7 +79,8 @@ Precondition: `spec.md` exists with no unresolved blocker.
69
79
  - concise for small, well-scoped formal requirements;
70
80
  - comprehensive for multi-module, public API, data model, security, permission, payment, deployment-impacting, or ambiguous requirements.
71
81
  4. Generate `plan.md` from `${SKILL_DIR}/assets/plan-template.md` with:
72
- - change approach;
82
+ - change approach and goal/constraint traceability;
83
+ - decision rationale and alternatives only when materially different viable paths exist;
73
84
  - component and file changes;
74
85
  - data migration approach when relevant;
75
86
  - interface/API contract design when relevant;
@@ -1,7 +1,18 @@
1
1
  # Plan: [TITLE]
2
2
 
3
3
  ## Change Approach
4
- [Description of the technical approach — how these changes integrate with the existing system]
4
+ [Description of the minimum-sufficient technical approach — how these changes integrate with the existing system]
5
+
6
+ ## Decision Traceability
7
+ | Goal / Constraint / Existing Contract / Evidenced Risk | Design Response | Evidence Status and Rationale | Completion Evidence |
8
+ |---|---|---|---|
9
+ | [G-1 or constraint] | [Necessary design response] | [confirmed fact / inference / recommendation / assumption] | [Observable test or check] |
10
+
11
+ ## Alternatives and Decision Rationale
12
+ <!-- Include only when materially different viable paths exist. Do not manufacture alternatives to fill this section. Delete when not applicable. -->
13
+ - Selected approach: [Complete meaning and why it fits the confirmed intent]
14
+ - Material alternatives: [Alternative + meaningful trade-off]
15
+ - Reconsider when: [Constraint or evidence change that would alter the decision]
5
16
 
6
17
  ## Component Design
7
18
 
@@ -85,12 +96,16 @@
85
96
  - [ ] CI/CD pipeline update needed
86
97
 
87
98
  ## Pre-Implementation Gates
88
- - [ ] Spec coverage: all goals mapped to components
99
+ - [ ] Intent fidelity: goals, success outcome, scope, and non-goals match the confirmed requirement
100
+ - [ ] Evidence honesty: facts, inferences, recommendations, assumptions, and unknowns remain distinct
101
+ - [ ] Spec coverage: all goals mapped to components and observable completion evidence
102
+ - [ ] Design necessity: every component/task maps to a goal, confirmed constraint, existing contract, or evidenced risk
103
+ - [ ] Minimum sufficiency: unsupported future work and unjustified abstractions are absent
89
104
  - [ ] Data model reviewed — existing schema conventions documented and followed (if applicable)
90
105
  - [ ] All `[NEEDS CLARIFICATION]` items resolved
91
106
  - [ ] Testing approach agreed
92
107
  - [ ] Behavior preservation strategy defined (if modifying existing behavior)
93
- - [ ] Root cause confirmed with reproduction test design (if fixing a defect)
108
+ - [ ] Root cause is confirmed with evidence or explicitly retained as a bounded hypothesis/unknown with reproduction and investigation tasks (if fixing a defect)
94
109
 
95
110
  ## Tasks
96
111
 
@@ -3,6 +3,13 @@
3
3
  ## Overview
4
4
  [One paragraph describing the purpose and motivation]
5
5
 
6
+ ## Intent and Evidence
7
+ - Confirmed intent: [User goal and successful outcome, expressed by complete meaning]
8
+ - Confirmed facts: [Evidence-backed current state and constraints]
9
+ - Evidence-backed inferences: [Inference + supporting evidence; delete if none]
10
+ - Assumptions: [Low-risk, local, reversible assumptions + verification point; delete if none]
11
+ - Unknowns: [Consequential unknowns use `[NEEDS CLARIFICATION]`; non-blocking unknowns retain their evidence status]
12
+
6
13
  ## Goals
7
14
 
8
15
  ### G-1: [Goal Title]
@@ -29,10 +36,12 @@
29
36
  - [Existing test suites that must continue to pass]
30
37
 
31
38
  ## Root Cause
32
- <!-- Include this section when the task is fixing a defect. Delete if not applicable. -->
39
+ <!-- Include this section when the task is fixing a defect. Delete if not applicable. Do not invent a root cause merely to complete the template. -->
33
40
  - Error classification: [Runtime / Network / Auth / Data / Logic / Config / External]
34
- - Root cause: [specific code location and mechanism]
35
- - Affected files: [file list with line numbers]
41
+ - Root-cause status: [confirmed / evidence-backed hypothesis / unknown]
42
+ - Root cause or hypothesis: [specific mechanism when supported; otherwise state the bounded investigation question]
43
+ - Evidence: [reproduction, failing test, trace, source observation, or other concrete basis]
44
+ - Affected files: [evidence-backed file list with purpose; use unknown when not established]
36
45
  - Impact: [blast radius — which modules / features are affected]
37
46
 
38
47
  ## Dependencies
@@ -62,7 +71,8 @@
62
71
  - [Constraint 1]
63
72
 
64
73
  ## Clarifications
65
- [NEEDS CLARIFICATION]: [Ambiguous item]
74
+ <!-- Use markers only for consequential ambiguity. Keep safe low-risk assumptions in Intent and Evidence instead of turning every uncertainty into a question. -->
75
+ [NEEDS CLARIFICATION]: [Decision, materially different outcomes, and why confirmation is required]
66
76
 
67
77
  ## Review Checklist
68
78
  - [ ] All goals have acceptance criteria
@@ -70,4 +80,6 @@
70
80
  - [ ] Dependencies are identified
71
81
  - [ ] No implementation details (WHAT not HOW)
72
82
  - [ ] Behavior preservation defined (if modifying existing behavior)
73
- - [ ] Root cause identified with evidence (if fixing a defect)
83
+ - [ ] Root cause is evidence-backed or explicitly labeled as hypothesis/unknown (if fixing a defect)
84
+ - [ ] Facts, inferences, recommendations, assumptions, and unknowns are not conflated
85
+ - [ ] Every goal has observable completion evidence and no scope item lacks a requirement or confirmed constraint
@@ -6,35 +6,36 @@ Invoked automatically during `/prizmkit-plan` Phase 0 (specify) when `[NEEDS CLA
6
6
 
7
7
  ## Question Strategy
8
8
 
9
- **Ask one question at a time.** Batching questions produces lower-quality answers.
9
+ Classify each uncertainty before asking:
10
10
 
11
- For each question:
12
- 1. Cite the exact location in spec.md (e.g., "§Goals G-1 says..." or "§Scope says...")
13
- 2. State what is ambiguous and why it matters for implementation
14
- 3. Provide a **recommended answer** with rationale — gives the user a concrete starting point to accept, modify, or reject
11
+ - **Consequential ambiguity** — different answers materially change the goal, external behavior, scope, compatibility, safety, cost, data, or an irreversible decision. Ask the user and keep `[NEEDS CLARIFICATION]` until resolved.
12
+ - **Evidence-resolvable uncertainty** — project docs, source, schemas, or existing contracts determine the answer. Inspect the bounded evidence and record the confirmed fact instead of asking.
13
+ - **Low-risk assumption** — the choice is local, reversible, and does not alter user-visible intent. Record the assumption and its verification point; let the user override it without blocking progress.
15
14
 
16
- **Prioritize by implementation impact** (highest first):
17
- 1. Data model (entities, relationships, field types, constraints, naming) — **hardest to change after code is written**
18
- 2. Functional scope boundaries
19
- 3. UX flow and error handling
20
- 4. Non-functional requirements (performance, security)
21
- 5. Edge cases and integration points
15
+ For each question or tightly related batch:
16
+ 1. Cite the exact location in `spec.md` (for example, "§Goals G-1" or "§Scope").
17
+ 2. State what is ambiguous, which outcomes differ, and why the decision is consequential.
18
+ 3. Provide an explicitly labeled **recommendation** with rationale when evidence supports one; it remains a recommendation until the user confirms it.
19
+ 4. Group questions that share one decision context. Ask sequentially only when one answer changes which later question is relevant.
20
+
21
+ Prioritize by consequence and reversibility, not by a universal domain order. Data integrity, safety, public contracts, and destructive migrations are commonly high impact; a data-model, UX, performance, or integration detail is consequential only when its alternatives materially change the requirement.
22
22
 
23
23
  ## Update Discipline
24
24
 
25
- After **each** user answer:
26
- - Immediately update `spec.md` (do not batch at the end)
27
- - Remove the resolved `[NEEDS CLARIFICATION]` marker
28
- - Re-evaluate for new ambiguities exposed by the answer
25
+ After each answer or related answer batch:
26
+ - Update `spec.md` with the complete selected meaning, not an answer token or conversation reference.
27
+ - Remove only the resolved `[NEEDS CLARIFICATION]` marker.
28
+ - Reclassify newly exposed uncertainty as consequential, evidence-resolvable, or a low-risk assumption.
29
29
 
30
- ## No Limits Policy
30
+ ## Convergence Policy
31
31
 
32
- **There is no cap on rounds or questions.** Keep asking until:
33
- - All `[NEEDS CLARIFICATION]` markers are removed, AND
34
- - No vague or underspecified areas remain, AND
35
- - You are fully confident about the requirements
32
+ Use no arbitrary target number of questions. Clarification converges when:
33
+ - no consequential `[NEEDS CLARIFICATION]` marker remains;
34
+ - confirmed facts, recommendations, assumptions, and unknowns are not conflated;
35
+ - unresolved low-risk assumptions are explicit and have a verification point; and
36
+ - the acceptance criteria let a fresh implementation session determine completion.
36
37
 
37
- If the user's answer raises new questions — ask those too. If a previously-resolved item needs revisiting due to new context — go back.
38
+ Do not keep questioning merely to reach subjective "full confidence" or specify low-level implementation choices that the plan can safely leave to implementation. If a user answer creates a new consequential conflict, surface that conflict and ask; otherwise preserve the uncertainty with its correct evidence status.
38
39
 
39
40
  ## Early Termination
40
41
 
@@ -62,6 +63,7 @@ If the user says "done", "stop", or "enough" — end immediately and output a su
62
63
 
63
64
  ## Guidelines
64
65
 
65
- - Stay at WHAT/WHY level — no implementation details (HOW) in spec
66
- - If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence
67
- - If the user seems fatigued: "I have N more questions — continue now or later?" — but never silently stop with unresolved ambiguities
66
+ - Stay at WHAT/WHY level — no implementation details (HOW) in spec.
67
+ - If an answer contradicts an existing requirement, surface the conflict and ask which takes precedence.
68
+ - Do not present a project default or general best practice as confirmed user intent.
69
+ - If the user seems fatigued, summarize the remaining consequential decisions and offer to continue now or save them as explicit blockers; do not silently default them.
@@ -30,13 +30,16 @@ Review both artifacts against these dimensions:
30
30
 
31
31
  | Dimension | Check |
32
32
  |---|---|
33
- | Ambiguity | Requirements, scope, terms, or expected behavior are unclear or internally inconsistent. |
33
+ | Intent fidelity | Goals, success outcomes, scope, non-goals, and constraint precedence preserve confirmed user meaning instead of substituting AI preferences or generic best practices. |
34
+ | Evidence status | Confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; consequential choices are not silently defaulted. |
35
+ | Ambiguity | Consequential requirements, scope, terms, or expected behavior are unclear or internally inconsistent; low-risk reversible assumptions are explicit rather than over-questioned. |
34
36
  | Acceptance criteria completeness | Each goal has verifiable acceptance criteria; edge/error cases are included when meaningful. |
35
37
  | Missing constraints | Security, data, compatibility, performance, platform, deployment, migration, or non-goal constraints are absent where relevant. |
36
38
  | Task ordering errors | Tasks are sequenced before their prerequisites, checkpoints are misplaced, or dependency order is unsafe. |
37
39
  | Dependency assumptions | The plan assumes missing APIs, schemas, files, services, packages, auth, environment variables, or generated artifacts without evidence. |
38
40
  | Scope drift | The plan adds unrelated work, backlog items, nice-to-haves, or implementation beyond the spec. |
39
- | Overengineering | The plan introduces abstractions, services, agents, workflows, data stores, or cross-module rewrites that the spec does not justify. |
41
+ | Overengineering | The plan introduces abstractions, services, agents, workflows, data stores, cross-module rewrites, or speculative future work that no goal, confirmed constraint, existing contract, or evidenced risk justifies. |
42
+ | Decision traceability | Every design element has a justified source and every goal maps to observable completion evidence; material alternatives are compared only when genuine viable paths exist. |
40
43
  | Implementation readiness | Tasks are actionable, file-scoped when possible, testable, and resumable; blockers are explicit. |
41
44
  | Source-reading overhead | The implementation plan avoids broad rereads and identifies the minimum context/files needed for execution. |
42
45
 
@@ -4,9 +4,16 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
4
4
 
5
5
  ---
6
6
 
7
+ ## Intent and Evidence
8
+
9
+ - [ ] Confirmed goals, successful outcomes, scope, non-goals, and explicit constraints preserve the user's meaning without adding AI preferences as requirements
10
+ - [ ] Confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns are labeled distinctly
11
+ - [ ] No consequential decision was silently defaulted in an interactive plan
12
+ - [ ] Low-risk assumptions are local, reversible, disclosed, and paired with a verification point
13
+
7
14
  ## Coverage
8
15
 
9
- - [ ] Every goal (G-N) in spec.md has at least one task in plan.md
16
+ - [ ] Every goal (G-N) in spec.md has at least one task in plan.md and observable completion evidence
10
17
  - [ ] Every task has a target file path (`— file: path/to/file`)
11
18
  - [ ] Risk assessment contains at least one concrete risk with a mitigation plan
12
19
  - [ ] The plan contains at least one verification checkpoint; a small plan may use one final checkpoint
@@ -18,15 +25,17 @@ Run this checklist after generating the Tasks section in plan.md. Fix any issues
18
25
  - [ ] No near-duplicate requirements exist across spec.md sections (same intent, different wording)
19
26
  - [ ] If duplicates found, consolidate to the clearer phrasing and remove the other
20
27
 
21
- ## Orphan Detection
28
+ ## Orphan and Design-Necessity Detection
22
29
 
23
- - [ ] No task exists without a mapped goal (orphan task)
24
- - [ ] No plan component exists without a corresponding spec requirement
30
+ - [ ] No task exists without a mapped goal, confirmed constraint, existing contract, or evidenced risk
31
+ - [ ] No plan component exists without a corresponding requirement or justified preservation obligation
32
+ - [ ] No speculative future feature, abstraction, infrastructure component, or cleanup expands the confirmed scope
25
33
 
26
34
  ## Ambiguity Scan
27
35
 
28
- - [ ] No unresolved `[NEEDS CLARIFICATION]`, TBD, TODO, or `???` markers remain
29
- - [ ] No vague criteria without measurable thresholds (e.g., "fast", "secure", "scalable", "intuitive" — replace with concrete numbers or conditions)
36
+ - [ ] No consequential `[NEEDS CLARIFICATION]`, TBD, TODO, or `???` marker remains
37
+ - [ ] Non-blocking unknowns and low-risk assumptions retain their evidence status instead of being presented as facts
38
+ - [ ] No vague criterion uses a measurable threshold unless that threshold is confirmed or supported by project evidence; otherwise clarify the observable condition
30
39
 
31
40
  ## Terminology Consistency
32
41
 
@@ -11,6 +11,15 @@ Plan executable refactoring items for later autonomous dev-pipeline execution. T
11
11
 
12
12
  Always produce a validated `.prizmkit/plans/refactor-list.json` that conforms to `dev-pipeline-refactor-list-v1`.
13
13
 
14
+ ## Intent-Aligned Planning Policy
15
+
16
+ Before proposing or finalizing refactor contracts:
17
+ 1. Establish the **intent baseline**: confirmed structural goal, preserved behavior, scope/non-goals, and explicit constraints. User requirements and confirmed decisions outrank AI preferences or general best practices; never silently violate safety, legal/privacy/data-integrity obligations, or verified existing contracts. Surface material conflicts instead.
18
+ 2. Maintain **evidence status**: distinguish confirmed facts, evidence-backed inferences, recommendations, assumptions, and unknowns. Never present an inferred target architecture or scope expansion as confirmed user intent.
19
+ 3. **Clarify by decision impact**. Ask before choices that materially change target structure, public contracts, behavior preservation, scope, compatibility, safety, cost, or irreversible migration state. Resolve from project evidence first; for low-risk, local, and reversible details, record a disclosed assumption instead of interrupting.
20
+ 4. Explore alternatives only when **materially different viable paths** exist. Compare meaningful architectural trade-offs without manufacturing an option count or applying a universal pattern.
21
+ 5. Produce a **minimum-sufficient** refactor contract: every operation maps to a confirmed structural goal, constraint, existing contract, or evidenced risk, and every preservation goal maps to observable completion evidence of equivalence. Defer unrelated cleanup and speculative redesign.
22
+
14
23
  ## Invocation Commitment (Hard Rule)
15
24
 
16
25
  **When the user invokes `/refactor-planner`, you MUST execute the refactor-planner workflow.** You must NEVER:
@@ -52,7 +61,7 @@ Every new or changed refactor item is an executable contract for a fresh AI sess
52
61
  1. **Self-contained contract**: The item's `description` and `acceptance_criteria`, read together, MUST define the objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, and completion evidence. Preserve substantive user requirements at matching detail.
53
62
  2. **Supplementary evidence only**: `user_context` is supplementary evidence only. It may contain scoped exact excerpts and purpose-tagged references, but it MUST NOT expand, replace, or contradict the contract. If `user_context` were removed, a fresh refactor session must still know the current structure, target architecture, allowed scope, forbidden changes, preservation strategy, and verification evidence.
54
63
  3. **Purposeful scope**: Every path in `scope.files` and every related path reference must be a purpose-tagged target path in the task contract or supplementary evidence, stating what to inspect or change. The scope array may remain schema-compatible path strings, while `description` explains each path or coherent path group's role.
55
- 4. **Clarify, do not guess**: Ask the user for clarification whenever target architecture, scope boundaries, preservation behavior, material applicability, or a relative reference has multiple plausible meanings.
64
+ 4. **Clarify by impact, do not guess**: Ask when multiple meanings of target architecture, scope boundaries, preservation behavior, material applicability, or relative references would materially change the refactor contract. Keep AI-proposed architecture labeled as a recommendation until confirmed; retain low-risk reversible implementation details as explicit assumptions when safe.
56
65
  5. **Item isolation**: Each refactor contract and its supplementary evidence contain only relevant goals, paths, constraints, desired end state, and preservation evidence.
57
66
 
58
67
  ### Artifact-Wide AI Readability
@@ -213,14 +222,14 @@ Support 4 input formats (users may mix formats):
213
222
  > "There's a circular dependency between auth and user modules"
214
223
  > "The database layer is tightly coupled to the HTTP layer"
215
224
 
216
- For each input, ask clarifying questions:
217
- - What is the specific target (files, modules, patterns), and what should the execution AI inspect at each purpose-tagged target path?
218
- - What is the complete desired target architecture or end state?
219
- - What are the scope boundaries and non-goals (must preserve API, must not touch certain files, rejected architecture that must stay rejected)?
220
- - Which behavior-preservation decisions and completion evidence prove the refactor is safe?
221
- - What is the motivation (maintainability, performance, testability)?
225
+ For each input, establish:
226
+ - The confirmed structural pain point and desired outcome.
227
+ - Evidence-backed target files, modules, patterns, consumers, and purpose-tagged inspection paths.
228
+ - Behavior invariants, public contracts, scope boundaries, and non-goals.
229
+ - Behavior-preservation and completion evidence.
230
+ - Motivation and constraints that determine whether a target architecture is necessary.
222
231
 
223
- Continue collecting goals until the user says they're done. There is no limit on rounds.
232
+ If the user has not selected a target architecture, inspect the code first and present a recommendation or meaningful alternatives only when materially different viable paths exist. Ask about consequential structure/scope/preservation decisions; group related questions and retain safe low-risk reversible details as explicit assumptions. Continue until the user indicates no additional goals and no consequential ambiguity remains.
224
233
 
225
234
  **CHECKPOINT CP-RP-1**: All refactoring goals collected and understood.
226
235
 
@@ -29,6 +29,9 @@ Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whethe
29
29
 
30
30
  For every reviewed refactor entry, check:
31
31
 
32
+ - Intent fidelity: confirmed structural outcome, behavior invariants, scope, non-goals, and constraints preserve user intent rather than an AI-selected architecture
33
+ - Evidence status honesty: current-state facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; proposed target architecture is not presented as confirmed until selected
34
+ - Minimum-sufficient scope: every operation maps to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk; unrelated cleanup and speculative redesign are absent
32
35
  - Schema compatibility with `dev-pipeline-refactor-list-v1` and `.prizmkit/dev-pipeline/templates/refactor-list-schema.json`
33
36
  - Dependency/DAG soundness, including safe behavior-preserving order
34
37
  - Description completeness: objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, completion evidence, and headless execution readiness
@@ -45,14 +48,15 @@ For every reviewed refactor entry, check:
45
48
 
46
49
  Repeat the pre-generation simulation for every reviewed new or changed refactor as if the reviewer has never seen the planning conversation. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
47
50
 
48
- 1. What exact problem or outcome is this task responsible for?
49
- 2. What current architecture exists and what target architecture must replace it?
51
+ 1. What exact confirmed structural problem or outcome is this task responsible for, and how does it preserve the intent baseline?
52
+ 2. What current architecture exists according to evidence, which target statements are confirmed versus recommended/assumed, and what target architecture must replace it?
50
53
  3. Which approach was selected, expressed by meaning rather than an option label?
51
54
  4. What scope boundaries, constraints, and non-goals must be preserved?
52
55
  5. Why is each reference material and target path relevant?
53
56
  6. How can completion and behavior preservation be verified?
54
57
  7. Does any phrase require an unseen earlier question, recommendation, or option list?
55
58
  8. Do quoted source materials agree with the final task decision?
59
+ 9. Does every operation have a confirmed structural goal, behavior invariant, existing contract, or evidenced risk, with no unrelated cleanup or speculative redesign?
56
60
 
57
61
  Return `NEEDS_FIXES` if any answer is missing, ambiguous, available only in `user_context`, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable refactor contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
58
62
 
@@ -9,8 +9,8 @@ Detailed procedures for Phases 4-6 of the refactor-planner interactive workflow,
9
9
  Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and dependency ordering rules.
10
10
 
11
11
  For each refactoring goal:
12
- 1. Identify atomic refactoring operations
13
- 2. Determine inter-item dependencies (safe renames first, structural changes later)
12
+ 1. Identify only the atomic operations necessary for the confirmed structural outcome; map each operation to a goal, behavior invariant, existing contract, or evidenced risk
13
+ 2. Determine inter-item dependencies from actual producer/consumer relationships; use safe renames before structural changes as a default heuristic, not a substitute for evidence
14
14
  3. Assess complexity per item from concrete indicators (file count, cross-module scope, public API/import-path impact, dependency depth, test coverage, behavior-preservation risk, migration impact)
15
15
  4. Assign priority from concrete impact (blocked delivery, correctness/security/data risk, maintainability value, or local cleanup), not from size or user urgency alone
16
16
  5. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
@@ -19,7 +19,7 @@ For each refactoring goal:
19
19
 
20
20
  ## Phase 5: Per-Item Confirmation Loop
21
21
 
22
- For each item, present the structured fields and use `AskUserQuestion` for the decision:
22
+ Present items in reviewable groups. Use `AskUserQuestion` for each consequential scope, target-architecture, public-contract, migration, or behavior-preservation decision; independent low-risk items may share one confirmation batch when their meanings remain clear:
23
23
 
24
24
  ```text
25
25
  Refactor Item R-001:
@@ -37,19 +37,21 @@ Refactor Item R-001:
37
37
  Dependencies: [none / R-002, R-003]
38
38
  ```
39
39
 
40
- Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified items before acceptance, and continue until all items are accepted or skipped.
40
+ Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified consequential items before acceptance. Do not ask the user to approve unconstrained implementation mechanics that preserve all confirmed boundaries and remain locally reversible.
41
41
 
42
42
  ---
43
43
 
44
44
  ## Phase 6: Completeness Review Checklist
45
45
 
46
- 1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Items should be ordered: safe renames -> extract/inline -> structural changes -> migrations
46
+ 1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Follow verified producer/consumer dependencies; otherwise prefer the risk-reducing order safe renames -> extract/inline -> structural changes -> migrations.
47
47
  2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
48
48
  3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
49
49
  4. **Cross-module impact**: Do any items affect modules outside the declared scope?
50
- 5. **Headless Context Completeness Gate**: Review every new or changed item as if the reviewer has never seen the planning conversation. Preserve unchanged historical items. Scan all AI-visible fields and sections first: every generated natural-language value in `project_description`, `global_context`, item fields, scope explanations, behavior-preservation/evidence text, `user_context`, comments, and parentheticals must be session-independent, with no dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance. Review changed root prose even when no refactor item changed. Then assess `description` plus `acceptance_criteria` without `user_context` and answer from the artifact alone:
51
- 1. What exact problem or outcome is this task responsible for?
52
- 2. What current architecture exists and what target architecture must replace it?
50
+ 5. **Intent and design necessity**: Does every item map to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk? Remove unrelated cleanup and speculative redesign.
51
+ 6. **Evidence status**: Are current-state observations, inferred architecture, recommendations, assumptions, and unknowns labeled distinctly? No AI-proposed architecture may appear as confirmed user intent without confirmation.
52
+ 7. **Headless Context Completeness Gate**: Review every new or changed item as if the reviewer has never seen the planning conversation. Preserve unchanged historical items. Scan all AI-visible fields and sections first: every generated natural-language value in `project_description`, `global_context`, item fields, scope explanations, behavior-preservation/evidence text, `user_context`, comments, and parentheticals must be session-independent, with no dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance. Review changed root prose even when no refactor item changed. Then assess `description` plus `acceptance_criteria` without `user_context` and answer from the artifact alone:
53
+ 1. What exact confirmed structural problem or outcome is this task responsible for, and how does it preserve the intent baseline?
54
+ 2. What current architecture exists according to evidence, which target statements are confirmed versus recommended/assumed, and what target architecture must replace it?
53
55
  3. Which approach was selected, expressed by meaning rather than an option label?
54
56
  4. What scope boundaries, constraints, and non-goals must be preserved?
55
57
  5. Why is each reference material and target path relevant, and what should be inspected?
@@ -57,6 +59,7 @@ Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified
57
59
  7. Which behavior-preservation decisions and completion evidence prove equivalence?
58
60
  8. Does any phrase require an unseen earlier question, recommendation, or option list?
59
61
  9. Do quoted source materials agree with the final task decision?
62
+ 10. Does every operation map to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk, with no unrelated cleanup or speculative redesign?
60
63
 
61
64
  Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available only in `user_context`. Parenthetical notes must pass the same gate. Do not emit transcript annotations such as `(original response: "...")`; preserve substantive rationale, but omit bare selection tokens and `全部按照推荐` or equivalent blanket recommendation approval after normalization. Ask the user for clarification when a relative statement has more than one plausible antecedent; never guess.
62
65
 
@@ -107,12 +110,14 @@ Flag items using `manual` strategy prominently — they carry the highest risk o
107
110
 
108
111
  ## Dependency Ordering
109
112
 
110
- Auto-detect inter-item dependencies and enforce safe ordering:
113
+ Auto-detect producer/consumer dependencies and enforce the resulting safe order. When no evidence requires another sequence, use this risk-reducing heuristic:
111
114
  1. **Safe renames** first (lowest risk, no structural change)
112
115
  2. **Extract/inline** operations (moderate risk, changes module boundaries)
113
116
  3. **Structural changes** (higher risk, reorganizes architecture)
114
117
  4. **Migrations** last (highest risk, changes patterns/paradigms)
115
118
 
119
+ Do not reorder items against verified dependencies merely to match the heuristic.
120
+
116
121
  ---
117
122
 
118
123
  ## Complexity Assessment
@@ -2,11 +2,13 @@
2
2
 
3
3
  This guide helps assess refactoring scope, determine the appropriate approach, and identify risks before decomposing into executable items.
4
4
 
5
+ Treat numeric thresholds and named patterns in this guide as evidence prompts, not user-intent overrides. Base the final scope, complexity, and decomposition on verified files, consumers, contracts, tests, and the confirmed structural goal. Label estimates as recommendations or assumptions until evidence supports them.
6
+
5
7
  ---
6
8
 
7
9
  ## 1. Scope Classification
8
10
 
9
- Every refactoring effort falls into one of three scope categories. Classification determines the planning depth required.
11
+ Classify the observed refactoring effort into the closest of three scope categories. Classification recommends planning depth; it does not expand the user's goal or make a larger target architecture mandatory.
10
12
 
11
13
  ### Incremental Refactoring
12
14
 
@@ -78,6 +80,8 @@ Before decomposing, assess the blast radius of the proposed refactoring.
78
80
 
79
81
  ### Impact Categories
80
82
 
83
+ Use file counts as an initial heuristic, then adjust from verified public contracts, dependency direction, behavior risk, and test coverage. A high count of mechanical import updates can be lower risk than one safety-critical public contract.
84
+
81
85
  | Affected Files | Impact Level | Planning Implication |
82
86
  |---------------|-------------|---------------------|
83
87
  | 1-3 | Low | Single item likely sufficient |
@@ -136,6 +140,8 @@ Assess risk for each refactoring item and for the overall plan.
136
140
 
137
141
  ### Per-Item Risk Factors
138
142
 
143
+ Use only measurements supported by repository evidence. If coverage, code age, complexity, or dependency counts are unknown, mark them unknown rather than selecting a risk band from intuition.
144
+
139
145
  | Factor | Low Risk | Medium Risk | High Risk |
140
146
  |--------|----------|-------------|-----------|
141
147
  | Test coverage | >80% on target | 40-80% | <40% |
@@ -167,7 +173,7 @@ Aggregate item risks to assess the plan:
167
173
 
168
174
  ### Splitting Heuristics
169
175
 
170
- Split a refactoring plan into multiple sessions when:
176
+ Treat these as triggers to assess a split, not automatic requirements. Split only when it reduces evidenced coordination, behavior-preservation, context, or rollback risk without breaking a necessary atomic migration:
171
177
 
172
178
  1. **Item count exceeds 8**: More than 8 items in a single plan increases coordination risk. Split into logical phases.
173
179
  2. **Estimated duration exceeds a day**: If the pipeline is expected to run for many hours, split at natural boundaries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "prizmkit",
3
- "version": "1.1.164",
3
+ "version": "1.1.165",
4
4
  "description": "Create a new PrizmKit-powered project with clean initialization — no framework dev files, just what you need.",
5
5
  "type": "module",
6
6
  "bin": {