prizmkit 1.1.179 → 1.1.181
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.
- package/bundled/VERSION.json +3 -3
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/bug-planner/SKILL.md +3 -3
- package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -0
- package/bundled/skills/feature-planner/SKILL.md +7 -7
- package/bundled/skills/feature-planner/assets/planning-guide.md +36 -40
- package/bundled/skills/feature-planner/references/completeness-review.md +4 -1
- package/bundled/skills/feature-planner/references/decomposition-patterns.md +1 -1
- package/bundled/skills/feature-planner/references/generated-plan-review.md +4 -0
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -0
- package/bundled/skills/feature-planner/references/new-project-planning.md +8 -7
- package/bundled/skills/feature-planner/scripts/validate-and-generate.py +10 -34
- package/bundled/skills/refactor-planner/SKILL.md +3 -3
- package/bundled/skills/refactor-planner/assets/planning-guide.md +20 -21
- package/bundled/skills/refactor-planner/references/fast-path.md +4 -5
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +3 -0
- package/bundled/skills/refactor-planner/references/planning-phases.md +1 -1
- package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +18 -15
- package/package.json +1 -1
package/bundled/VERSION.json
CHANGED
|
@@ -57,11 +57,11 @@ In an ordinary successful flow, `.prizmkit/plans/bug-fix-list.draft.json` is int
|
|
|
57
57
|
|
|
58
58
|
Every new or changed bug is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
|
|
59
59
|
|
|
60
|
-
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`.
|
|
60
|
+
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`. AI rewrite is allowed; dropping a confirmed item is not. There is no word-count upper limit and no acceptance-criteria count upper limit.
|
|
61
61
|
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.
|
|
62
62
|
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.
|
|
63
63
|
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.
|
|
64
|
-
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.
|
|
64
|
+
5. **Bug isolation**: Keep one bug per task unless bugs share the same root cause or the same failing contract and the user confirms a merge. Do not domain-merge unrelated bugs merely because they sit in the same module. Each bug contract and its supplementary evidence contain only material relevant to that bug. Repeat shared environment or constraints only when explicitly global.
|
|
65
65
|
|
|
66
66
|
### Artifact-Wide AI Readability
|
|
67
67
|
|
|
@@ -317,7 +317,7 @@ Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available onl
|
|
|
317
317
|
**Step 2 — Acceptance criteria specificity check**: For each bug, verify each acceptance criterion passes the "pipeline autonomy test" — could an AI session, without asking a human, determine whether this criterion is met? Flag criteria that are subjective ("works correctly"), lack measurable conditions ("performs better"), omit expected behavior, or leave reproduction and verification decisions only in `user_context`.
|
|
318
318
|
|
|
319
319
|
**Step 3 — Cross-bug analysis**: Check for:
|
|
320
|
-
- **Root cause overlap**: Multiple bugs in the same module
|
|
320
|
+
- **Root cause overlap**: Keep one bug per task. Multiple bugs in the same module are not merged by module. Merge only when they share the same root cause or the same failing contract and the user confirms.
|
|
321
321
|
- **Missing dependencies**: If fixing B-002 requires B-001 to be fixed first, flag the dependency
|
|
322
322
|
- **Scope gaps**: If bugs describe symptoms but the underlying cause likely affects more areas, suggest additional bugs
|
|
323
323
|
|
|
@@ -45,6 +45,9 @@ For every reviewed bug entry, check:
|
|
|
45
45
|
- Task-scoped `user_context` isolation: no unrelated sibling bug descriptions, logs, stack traces, reproduction steps, expected/actual behavior notes, or supplementary materials; shared context appears on multiple bugs only when explicitly global
|
|
46
46
|
- Purpose-tagged stable code, configuration, machine-consumed interface, and URL references; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
|
|
47
47
|
- Severity/priority calibration: every reviewed bug has a short severity rationale and priority rationale, the preserved severity-to-priority mapping is followed, and high priority is not used without core outage, data loss/integrity, security/auth, timeout/crash, or no-workaround indicators
|
|
48
|
+
- Incident scope: keep one bug per task unless the same root cause or same failing contract is confirmed; do not domain-merge by module
|
|
49
|
+
- Injected-field fidelity: confirmed actual/expected behavior and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
|
|
50
|
+
- Size: there is no word-count upper limit and no acceptance-criteria count upper limit
|
|
48
51
|
- Browser interaction and verification fields for UI-reproducible bugs when applicable
|
|
49
52
|
|
|
50
53
|
## Headless Context Completeness Gate
|
|
@@ -65,14 +65,14 @@ In an ordinary successful flow, `.prizmkit/plans/feature-list.draft.json` is int
|
|
|
65
65
|
|
|
66
66
|
Every new or changed feature is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
|
|
67
67
|
|
|
68
|
-
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.
|
|
68
|
+
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. AI rewrite is allowed; dropping a confirmed item is not. There is no word-count upper limit and no acceptance-criteria count upper limit.
|
|
69
69
|
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.
|
|
70
70
|
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.
|
|
71
|
-
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.
|
|
71
|
+
4. **Feature isolation**: In multi-feature planning, each written task contract and its supplementary evidence contain only material relevant to that feature. Repeat shared context only when it explicitly applies to every affected feature. Isolation does not mean split by module or directory. **Domain grouping**: Group by contract-bounded capability — shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract in `description` and `acceptance_criteria`; independently shippable is not a split reason. Before the first user-facing feature table, merge same-domain over-split. Coverage is not one ID per complaint. Ask the user only when two groupings would materially change task boundaries.
|
|
72
72
|
|
|
73
73
|
### Artifact-Wide AI Readability
|
|
74
74
|
|
|
75
|
-
- Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, rationales, `
|
|
75
|
+
- Every generated natural-language value must be a standalone domain statement. This applies to all AI-visible fields and sections, including `project_description`, `global_context`, titles, descriptions, acceptance criteria, rationales, `completion_notes`, `testing`, `user_context`, evidence and environment text, browser verification goals, comments, appendices, and parentheticals.
|
|
76
76
|
- Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
|
|
77
77
|
- Never emit dialogue-role or chronology labels such as `user said`, `user answered`, `original request`, `this round`, `previous discussion`, `as discussed earlier`, `用户本轮回答`, or `如前面讨论`. Never emit planning question IDs, answer tokens, planning-option recommendation markers, checkpoint provenance, or raw internal answer-map entries as domain content.
|
|
78
78
|
- `user_context` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct product behavior, constraints, rationale, or verification evidence before generation.
|
|
@@ -118,7 +118,7 @@ Trigger conditions are covered by the frontmatter `description`. Do NOT use this
|
|
|
118
118
|
## Resource Loading Rules (Mandatory)
|
|
119
119
|
|
|
120
120
|
1. **Planning reference** — load before writing feature descriptions:
|
|
121
|
-
- Read `${SKILL_DIR}/assets/planning-guide.md` for description writing standards, acceptance criteria patterns, complexity estimation, dependency rules, and
|
|
121
|
+
- Read `${SKILL_DIR}/assets/planning-guide.md` for description writing standards, acceptance criteria patterns, complexity estimation, dependency rules, and contract-bounded grouping. Apply that grouping before the first user-facing feature table.
|
|
122
122
|
|
|
123
123
|
2. **Incremental planning reference** — load for incremental mode:
|
|
124
124
|
- Read `${SKILL_DIR}/references/incremental-feature-planning.md`
|
|
@@ -305,7 +305,7 @@ Execute the planning workflow in conversation mode with mandatory checkpoints:
|
|
|
305
305
|
|
|
306
306
|
If the user provides materials, require or infer only when unambiguous a task-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch them before Phase 2. For web links, retrieve and analyze the relevant content; for images, analyze the relevant visual evidence. Material ingestion follows the same durability rule as final output: copy or normalize task-relevant requirements and exact evidence, omit transient non-code paths, and retain only purpose-tagged stable execution-time sources. Do not copy complete large materials merely to preserve them.
|
|
307
307
|
2. Confirm constraints and existing architecture
|
|
308
|
-
3. Propose feature set with dependencies
|
|
308
|
+
3. Propose feature set with dependencies. **Contract-bounded over-split (Hard Rule)** — Before the first user-facing feature table, merge items that share one contract-bounded capability. Walkthrough notes, complaints, empty states, and button copy default into few capabilities; one complaint per row is forbidden. Long description, many acceptance criteria, and changing frontend and backend together are not split reasons. Split into additional top-level features only when implementation plus verification clearly cannot finish in one existing headless session, typically after two or more heavy capability seams. Ask the user only when two groupings would materially change task boundaries. Present the contract-grained table and note which complaints landed in which item. Users confirm coverage and contract cuts, not a UI-part menu.
|
|
309
309
|
4. Refine descriptions and acceptance criteria
|
|
310
310
|
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.
|
|
311
311
|
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.
|
|
@@ -324,7 +324,7 @@ Checkpoints catch cascading errors early — skipping one means the next phase b
|
|
|
324
324
|
| Checkpoint | Artifact/State | Criteria | Phase |
|
|
325
325
|
|-----------|----------------|----------|-------|
|
|
326
326
|
| **CP-FP-1** | Scope Confirmed | User confirmed what features to plan and context understood | 1 |
|
|
327
|
-
| **CP-FP-2** | Feature Proposals | Feature set with titles+deps identified (pre-validation) | 3-5 |
|
|
327
|
+
| **CP-FP-2** | Feature Proposals | Feature set with titles+deps identified after same-domain over-split (pre-validation); first table is contract-grained | 3-5 |
|
|
328
328
|
| **CP-FP-3** | DAG Validity | No cycles, dependencies resolved (validation dry-run) | 5 |
|
|
329
329
|
| **CP-FP-3.1** | Browser Interaction Applied | Qualifying features have `browser_interaction` field; user confirmed or opted out | 4 |
|
|
330
330
|
| **CP-FP-3.2** | Testing Defaults Applied | All features have appropriate testing expectations | 7 |
|
|
@@ -420,7 +420,7 @@ Key requirements:
|
|
|
420
420
|
- new items default `status: "pending"`
|
|
421
421
|
- English feature titles for stable slug generation
|
|
422
422
|
- `browser_interaction` auto-generated for qualifying frontend features (with `tool` selection: `auto`/`playwright-cli`/`opencli`)
|
|
423
|
-
- descriptions: minimum 15 words (error), recommended minimum 30/50/80/100+ for low/medium/high/critical (warning).
|
|
423
|
+
- descriptions: minimum 15 words (error), recommended minimum 30/50/80/100+ for low/medium/high/critical (warning). There is no word-count upper limit and no acceptance-criteria count upper limit. Keep `description` plus `acceptance_criteria` complete without `user_context`.
|
|
424
424
|
- `estimated_complexity` records implementation scope and verification risk for planning summaries, ordering, and downstream context. It does not select a fixed agent count or named review topology; every normal feature session receives the runtime's full guidance.
|
|
425
425
|
|
|
426
426
|
**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Feature Planning Reference Guide
|
|
2
2
|
|
|
3
|
-
This guide provides structured templates and patterns for writing high-quality feature descriptions, acceptance criteria, complexity estimates, dependency graphs, and
|
|
3
|
+
This guide provides structured templates and patterns for writing high-quality feature descriptions, acceptance criteria, complexity estimates, dependency graphs, and contract-bounded grouping decisions. Use during feature-planner sessions.
|
|
4
4
|
|
|
5
5
|
For app-level design references (vision templates, tech stack matrix), see `app-planner/references/app-design-guide.md`. For feature decomposition patterns (CRUD, SaaS, Social, E-commerce), see `${SKILL_DIR}/references/decomposition-patterns.md`.
|
|
6
6
|
|
|
@@ -21,7 +21,7 @@ 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 schema-level upper limit, but length is not a quality target.
|
|
24
|
+
There is no schema-level upper limit, but length is not a quality target. There is no word-count upper limit and no acceptance-criteria count upper limit. Do not pad with unconfirmed HOW. Add confirmed intent only; AI rewrite is allowed; dropping a confirmed item is not. 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
|
|
|
@@ -125,7 +125,7 @@ Then [expected outcome]
|
|
|
125
125
|
2. **No implementation details.** Criteria describe what, not how. Say "user is redirected" not "React Router navigates to /dashboard."
|
|
126
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
|
-
5. **Keep
|
|
128
|
+
5. **Keep every confirmed criterion.** There is no acceptance-criteria count upper limit. Do not merge or drop confirmed completion evidence to stay under a count.
|
|
129
129
|
|
|
130
130
|
---
|
|
131
131
|
|
|
@@ -151,20 +151,22 @@ Use at least two relevant indicators in each `estimated_complexity` rationale:
|
|
|
151
151
|
- acceptance-criteria count and edge-case breadth
|
|
152
152
|
- existing test coverage and verification difficulty
|
|
153
153
|
|
|
154
|
-
### Complexity
|
|
154
|
+
### Complexity Labeling Notes
|
|
155
155
|
|
|
156
|
-
|
|
156
|
+
Acceptance-criteria count, file count, and module count may raise the complexity **label**. They are not split reasons. Independently shippable is not a split reason.
|
|
157
|
+
|
|
158
|
+
Split a feature into additional **top-level** items only when implementation plus verification clearly cannot finish in one existing headless session, typically after crossing two or more heavy capability seams of one contract-bounded capability. Directory names are clues, not the grouping authority.
|
|
159
|
+
|
|
160
|
+
Do not split merely because of:
|
|
157
161
|
|
|
158
162
|
- More than 8 acceptance criteria.
|
|
159
163
|
- Touches more than 3 distinct modules or layers.
|
|
160
|
-
-
|
|
161
|
-
-
|
|
162
|
-
- Contains both real-time and batch processing requirements.
|
|
163
|
-
- Needs new infrastructure (e.g., message queue, search index) AND application logic.
|
|
164
|
+
- Frontend and backend work in the same contract-bounded capability.
|
|
165
|
+
- Complexity `high`.
|
|
164
166
|
|
|
165
167
|
### Estimation Consistency Rules
|
|
166
168
|
|
|
167
|
-
- If a feature is marked as `low` complexity,
|
|
169
|
+
- If a feature is marked as `low` complexity, its **label** usually matches a small surface; many confirmed acceptance criteria raise the label rather than forcing a split or dropped criteria.
|
|
168
170
|
- If a feature is marked as `medium` complexity, explain why the scope is bounded even if it touches multiple files.
|
|
169
171
|
- If a feature is marked as `high` complexity, it must have a clear concrete justification (e.g., "payment processing with webhook idempotency across API, persistence, and worker modules").
|
|
170
172
|
- Use `critical` complexity only for features requiring architectural changes that touch 10+ files, involve cross-module API surface changes, or need stronger review and test gates for safety.
|
|
@@ -210,44 +212,38 @@ These rules ensure the feature dependency graph is valid and buildable.
|
|
|
210
212
|
|
|
211
213
|
---
|
|
212
214
|
|
|
213
|
-
##
|
|
214
|
-
|
|
215
|
-
Session granularity determines whether a feature is implemented in a single coding session or split across multiple sub-feature sessions.
|
|
215
|
+
## Contract-Bounded Grouping Rules
|
|
216
216
|
|
|
217
|
-
|
|
217
|
+
A **contract-bounded capability** is one business capability whose later session would still need the earlier session's shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract (`description` plus `acceptance_criteria`); independently shippable is not a split reason. Directories and package names are clues only.
|
|
218
218
|
|
|
219
|
-
|
|
220
|
-
|-----------|-------------|-------|
|
|
221
|
-
| Acceptance criteria <= 5 | `feature` | Single session can handle it |
|
|
222
|
-
| Acceptance criteria 6-8 | `feature` or `auto` | Use judgment based on complexity |
|
|
223
|
-
| Acceptance criteria > 8 | `auto` | Define sub_features |
|
|
224
|
-
| Touches <= 2 modules | `feature` | Focused enough for one session |
|
|
225
|
-
| Touches 3+ modules | `auto` | Split by module boundary |
|
|
226
|
-
| Complexity "low" | `feature` | Always single session |
|
|
227
|
-
| Complexity "high" + many criteria | `auto` | Always consider splitting |
|
|
219
|
+
Runtime runs one fresh session per top-level feature.
|
|
228
220
|
|
|
229
|
-
|
|
221
|
+
Default: one top-level feature per contract-bounded capability, even when large. Split into additional top-level features only when implementation plus verification clearly cannot finish in one existing headless session, typically after two or more heavy capability seams. Each resulting item still needs a complete `description` plus `acceptance_criteria`.
|
|
230
222
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
```
|
|
234
|
-
F-003-A: Backend API for [entity] CRUD
|
|
235
|
-
F-003-B: Frontend UI for [entity] management
|
|
236
|
-
F-003-C: Integration tests for [entity] workflows
|
|
237
|
-
```
|
|
223
|
+
### Before the first user-facing table
|
|
238
224
|
|
|
239
|
-
|
|
225
|
+
Run this over-split before presenting titles and dependencies (Phase 3 / CP-FP-2), not only during Phase 6 completeness review:
|
|
240
226
|
|
|
241
|
-
|
|
227
|
+
- Shared domain objects, state machine, invariants, public API, and error semantics → one top-level feature
|
|
228
|
+
- Walkthrough notes, complaints, empty states, and button copy: merge into few capabilities first; one complaint per row is forbidden
|
|
229
|
+
- Long `description`, many acceptance criteria, and changing frontend and backend together are not split reasons
|
|
230
|
+
- Ask only when two groupings would materially change task boundaries. Default to the contract-grained table and note which complaints landed in which item.
|
|
242
231
|
|
|
243
|
-
|
|
232
|
+
Phase 6 same-domain over-split remains `NEEDS_FIXES` and may still merge. A previously shown row count is not a freeze.
|
|
244
233
|
|
|
245
|
-
|
|
234
|
+
### Misread contrast
|
|
246
235
|
|
|
247
|
-
|
|
236
|
+
| Easy misread | Actual requirement |
|
|
237
|
+
|---|---|
|
|
238
|
+
| Do not drop confirmed requirements | Write the behavior into the same contract. Coverage is not one ID per complaint |
|
|
239
|
+
| One session per feature, so smaller tickets run better | Forbidden as a split reason; prefer one long contract with many acceptance criteria |
|
|
240
|
+
| User confirms which features to plan | Confirming coverage and contract cuts is not the same as confirming how many table rows |
|
|
248
241
|
|
|
249
|
-
###
|
|
242
|
+
### Examples
|
|
250
243
|
|
|
251
|
-
-
|
|
252
|
-
-
|
|
253
|
-
-
|
|
244
|
+
- Merge: payment capture, refund, and payment callbacks share money/idempotency contracts → one feature. The contract may be long and may have many acceptance criteria.
|
|
245
|
+
- Split across domains: payment vs inventory stock reservation (different core contracts) → two features.
|
|
246
|
+
- Overflow split: one payment domain that cannot finish in one existing headless session → two top-level features at capability seams (for example user capture vs payouts).
|
|
247
|
+
- Walkthrough / complaint list:
|
|
248
|
+
- Bad: a long interaction-complaint list becomes one feature per UI region (search box, unsaved-change dialog, drag-and-drop, preview pane, URL/tab state each get their own ID).
|
|
249
|
+
- Good: shared resource identity and the same mutation/error contract stay one top-level feature. Empty states and button copy land in that same contract. A genuinely separate contract (for example navigation identity that is not the same resource/mutation contract) may be a second top-level feature.
|
|
@@ -29,7 +29,7 @@ If any consequential answer is unavailable, ambiguous, or present only in `user_
|
|
|
29
29
|
|
|
30
30
|
## Step 2: Contract and Material Checks
|
|
31
31
|
|
|
32
|
-
- Preserve substantive user requirements, rationale, and constraints at matching detail;
|
|
32
|
+
- Preserve substantive user requirements, rationale, and constraints at matching detail; AI rewrite is allowed; dropping a confirmed item is not.
|
|
33
33
|
- Expand option shorthand into complete selected meaning, for example: `Selected decision: use cursor pagination with a 50-item default`.
|
|
34
34
|
- Do not emit transcript annotations such as `(original response: "...")`; parenthetical content must also be independently intelligible and materially useful.
|
|
35
35
|
- Resolve `方案B`, `按推荐走`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification.
|
|
@@ -63,6 +63,9 @@ Look at the feature set as a whole:
|
|
|
63
63
|
- **Design necessity**: Does every prescribed component, interface, or dependency map to confirmed intent, an existing contract, or an evidenced risk?
|
|
64
64
|
- **Evidence status**: Are recommendations and inferred implementation details clearly separated from confirmed product decisions?
|
|
65
65
|
- **Source conflict**: Does an excerpt describe an earlier alternative that conflicts with the selected final decision?
|
|
66
|
+
- **same-domain over-split**: Do two new or changed items share one contract-bounded capability without an existing-headless-session overflow exception? If yes, merge them. Independently shippable is not a split reason. This gate may still merge after a table was shown; a previously shown row count is not a freeze.
|
|
67
|
+
- **unused nested work**: Does a new or changed item store required work only in `user_context`? If yes, `NEEDS_FIXES` — move it into `description` and `acceptance_criteria`.
|
|
68
|
+
- **size caps**: Do not treat long descriptions or many acceptance criteria as defects. There is no word-count upper limit and no acceptance-criteria count upper limit.
|
|
66
69
|
|
|
67
70
|
## Step 4: Present Review and Repair
|
|
68
71
|
|
|
@@ -71,5 +71,5 @@ F-010: Admin Dashboard (deps: F-006, F-007)
|
|
|
71
71
|
|
|
72
72
|
- Every app starts with an infrastructure/setup feature (F-001) that has zero dependencies.
|
|
73
73
|
- Authentication almost always comes second unless the app is fully public.
|
|
74
|
-
- Group related functionality into single
|
|
74
|
+
- Group related functionality into a single contract-bounded capability rather than splitting too finely. Independently shippable is not a split reason.
|
|
75
75
|
- If a pattern does not match the app being planned, combine elements from multiple patterns or define a custom decomposition from scratch.
|
|
@@ -45,6 +45,10 @@ For every reviewed feature entry, check:
|
|
|
45
45
|
- Task-scoped `user_context` isolation: no unrelated sibling feature descriptions, file references, or supplementary materials; shared context appears on multiple items only when explicitly global
|
|
46
46
|
- Purpose-tagged stable code, configuration, machine-consumed interface, and URL references; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
|
|
47
47
|
- Priority/complexity calibration: every reviewed feature has short priority and complexity rationales, medium/low assignments are allowed when criteria fit, and high/high is not used merely because work is framework-related, multi-file, or user-requested
|
|
48
|
+
- Domain cohesion: same contract-bounded capability stays one top-level item; independently shippable is not a split reason; same-domain over-split is `NEEDS_FIXES` unless implementation plus verification cannot finish in one existing headless session
|
|
49
|
+
- Unused nested work: new or changed items MUST NOT store required work only in `user_context`; move it into `description` and `acceptance_criteria`
|
|
50
|
+
- Injected-field fidelity: confirmed WHAT, constraints, non-goals, boundaries, and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
|
|
51
|
+
- Size: there is no word-count upper limit and no acceptance-criteria count upper limit; long contracts are not defects
|
|
48
52
|
- Browser interaction fields for qualifying frontend/fullstack features when applicable
|
|
49
53
|
|
|
50
54
|
## Headless Context Completeness Gate
|
|
@@ -56,6 +56,8 @@ Use current project evidence as the primary source. The recent five-task window
|
|
|
56
56
|
|
|
57
57
|
Draft new items only; do not rewrite old validated features unless the user explicitly requested an old ID operation.
|
|
58
58
|
|
|
59
|
+
Group the increment by contract-bounded capability before presenting or writing the additions table. A long idea or complaint list is not one new ID per idea. Merge first; split into additional top-level additions only when one existing headless session cannot finish and the cut is at a heavy capability seam.
|
|
60
|
+
|
|
59
61
|
For each new feature:
|
|
60
62
|
- assign the next sequential ID returned by `context`;
|
|
61
63
|
- omit `status` or set it to `pending`;
|
|
@@ -117,6 +119,7 @@ Use concise prompts during interaction:
|
|
|
117
119
|
- [ ] Bounded `context` command used; complete historical list not loaded
|
|
118
120
|
- [ ] At most five recent `{id, description}` pairs inspected
|
|
119
121
|
- [ ] No historical content added by default
|
|
122
|
+
- [ ] Increment grouped by contract before presenting or writing the additions table
|
|
120
123
|
- [ ] Any incorporated history is minimum, contract-affecting, and task-scoped
|
|
121
124
|
- [ ] Old dependency IDs represent real execution prerequisites
|
|
122
125
|
- [ ] Additions-only draft contains no root metadata or historical features
|
|
@@ -23,7 +23,7 @@ Read `.prizmkit/config.json`, `.prizmkit/plans/project-brief.md`, `.prizmkit/pri
|
|
|
23
23
|
Rules:
|
|
24
24
|
- Include foundational setup feature first only when the existing project still needs setup work.
|
|
25
25
|
- Aim 5-12 features for an initial executable plan unless the user explicitly scopes smaller.
|
|
26
|
-
- Keep each feature implementable in one pipeline unit unless
|
|
26
|
+
- Keep each feature implementable in one pipeline unit unless implementation plus verification cannot finish in one existing headless session.
|
|
27
27
|
|
|
28
28
|
For each feature define:
|
|
29
29
|
- `id`
|
|
@@ -44,12 +44,13 @@ Check:
|
|
|
44
44
|
- order is executable
|
|
45
45
|
- priorities align with delivery value and risk
|
|
46
46
|
|
|
47
|
-
### Phase 5:
|
|
47
|
+
### Phase 5: Contract-Bounded Grouping
|
|
48
48
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
-
|
|
52
|
-
-
|
|
49
|
+
Group by contract-bounded capability. Independently shippable is not a split reason. Run this grouping before the first user-facing feature table, including the initial MVP proposal.
|
|
50
|
+
|
|
51
|
+
Split into additional top-level features only when:
|
|
52
|
+
- implementation plus verification cannot finish in one existing headless session
|
|
53
|
+
- the split is at a capability seam, and each item has a complete `description` plus `acceptance_criteria`
|
|
53
54
|
|
|
54
55
|
### Phase 6: Generate + Validate
|
|
55
56
|
|
|
@@ -71,7 +72,7 @@ Split into `sub_features` when:
|
|
|
71
72
|
- Medium complexity: ≥50 words — add integration points, data model overview, error handling approach
|
|
72
73
|
- High complexity: ≥80 words — add architecture decisions, performance considerations, security implications, migration strategy if applicable
|
|
73
74
|
- Description must cover what, integration points, key behaviors, data model when applicable, and error/edge cases.
|
|
74
|
-
- Write at least 1 testable acceptance criterion to satisfy schema validation.
|
|
75
|
+
- Write at least 1 testable acceptance criterion to satisfy schema validation. There is no acceptance-criteria count upper limit; keep every confirmed criterion.
|
|
75
76
|
- Keep dependency graph simple and explicit.
|
|
76
77
|
|
|
77
78
|
## Final Delivery Checklist
|
|
@@ -380,25 +380,16 @@ def validate_feature_list(data, is_new_plan=True):
|
|
|
380
380
|
else:
|
|
381
381
|
complexity_dist[complexity] += 1
|
|
382
382
|
|
|
383
|
-
# --
|
|
383
|
+
# -- Optional leftover keys (historical lists only; not taught for new items) --
|
|
384
384
|
granularity = feat.get("session_granularity")
|
|
385
|
-
if granularity is not None:
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
label, granularity, ", ".join(sorted(VALID_GRANULARITIES))
|
|
390
|
-
)
|
|
385
|
+
if granularity is not None and granularity not in VALID_GRANULARITIES:
|
|
386
|
+
errors.append(
|
|
387
|
+
"{}: session_granularity '{}' invalid, must be one of: {}".format(
|
|
388
|
+
label, granularity, ", ".join(sorted(VALID_GRANULARITIES))
|
|
391
389
|
)
|
|
392
|
-
|
|
393
|
-
subs = feat.get("sub_features")
|
|
394
|
-
if not isinstance(subs, list) or len(subs) == 0:
|
|
395
|
-
warnings.append(
|
|
396
|
-
"{}: granularity is 'auto' but no sub_features defined".format(label)
|
|
397
|
-
)
|
|
390
|
+
)
|
|
398
391
|
|
|
399
|
-
# -- Sub-features --
|
|
400
392
|
subs = feat.get("sub_features")
|
|
401
|
-
|
|
402
393
|
# -- Browser interaction check (warning for frontend features) --
|
|
403
394
|
has_frontend = bool(
|
|
404
395
|
data.get("global_context", {}).get("frontend_framework")
|
|
@@ -519,8 +510,6 @@ def generate_template():
|
|
|
519
510
|
"Linting and formatting configured",
|
|
520
511
|
],
|
|
521
512
|
"status": "pending",
|
|
522
|
-
"session_granularity": "feature",
|
|
523
|
-
"sub_features": [],
|
|
524
513
|
}
|
|
525
514
|
],
|
|
526
515
|
"global_context": {
|
|
@@ -609,8 +598,8 @@ def generate_summary_markdown(data):
|
|
|
609
598
|
lines.append("")
|
|
610
599
|
|
|
611
600
|
# Table header
|
|
612
|
-
lines.append("| ID | Title | Complexity | Priority | Dependencies | Criteria |
|
|
613
|
-
lines.append("
|
|
601
|
+
lines.append("| ID | Title | Complexity | Priority | Dependencies | Criteria |")
|
|
602
|
+
lines.append("|----|-------|------------|----------|--------------|----------|")
|
|
614
603
|
|
|
615
604
|
for feat in features:
|
|
616
605
|
fid = feat.get("id", "?")
|
|
@@ -620,10 +609,9 @@ def generate_summary_markdown(data):
|
|
|
620
609
|
deps = feat.get("dependencies", [])
|
|
621
610
|
deps_str = ", ".join(deps) if deps else "-"
|
|
622
611
|
criteria_count = len(feat.get("acceptance_criteria", []))
|
|
623
|
-
granularity = feat.get("session_granularity", "-")
|
|
624
612
|
|
|
625
|
-
lines.append("| {} | {} | {} | {} | {} | {} |
|
|
626
|
-
fid, title, complexity, priority, deps_str, criteria_count
|
|
613
|
+
lines.append("| {} | {} | {} | {} | {} | {} |".format(
|
|
614
|
+
fid, title, complexity, priority, deps_str, criteria_count
|
|
627
615
|
))
|
|
628
616
|
|
|
629
617
|
lines.append("")
|
|
@@ -637,21 +625,15 @@ def generate_summary_markdown(data):
|
|
|
637
625
|
|
|
638
626
|
# Statistics
|
|
639
627
|
complexity_dist = {"low": 0, "medium": 0, "high": 0, "critical": 0}
|
|
640
|
-
total_sub = 0
|
|
641
628
|
for feat in features:
|
|
642
629
|
c = feat.get("estimated_complexity")
|
|
643
630
|
if c in complexity_dist:
|
|
644
631
|
complexity_dist[c] += 1
|
|
645
|
-
subs = feat.get("sub_features")
|
|
646
|
-
if isinstance(subs, list):
|
|
647
|
-
total_sub += len(subs)
|
|
648
632
|
|
|
649
633
|
_, max_depth = _detect_cycles(features)
|
|
650
634
|
|
|
651
635
|
lines.append("## Statistics")
|
|
652
636
|
lines.append("- Total features: {}".format(len(features)))
|
|
653
|
-
if total_sub > 0:
|
|
654
|
-
lines.append("- Total sub-features: {}".format(total_sub))
|
|
655
637
|
lines.append("- Complexity: {} low, {} medium, {} high, {} critical".format(
|
|
656
638
|
complexity_dist["low"], complexity_dist["medium"],
|
|
657
639
|
complexity_dist["high"], complexity_dist["critical"]
|
|
@@ -666,14 +648,10 @@ def generate_summary_json(data):
|
|
|
666
648
|
features = data.get("features", [])
|
|
667
649
|
|
|
668
650
|
complexity_dist = {"low": 0, "medium": 0, "high": 0, "critical": 0}
|
|
669
|
-
total_sub = 0
|
|
670
651
|
for feat in features:
|
|
671
652
|
c = feat.get("estimated_complexity")
|
|
672
653
|
if c in complexity_dist:
|
|
673
654
|
complexity_dist[c] += 1
|
|
674
|
-
subs = feat.get("sub_features")
|
|
675
|
-
if isinstance(subs, list):
|
|
676
|
-
total_sub += len(subs)
|
|
677
655
|
|
|
678
656
|
has_cycles, max_depth = _detect_cycles(features)
|
|
679
657
|
|
|
@@ -686,7 +664,6 @@ def generate_summary_json(data):
|
|
|
686
664
|
"estimated_complexity": feat.get("estimated_complexity"),
|
|
687
665
|
"dependencies": feat.get("dependencies", []),
|
|
688
666
|
"acceptance_criteria_count": len(feat.get("acceptance_criteria", [])),
|
|
689
|
-
"session_granularity": feat.get("session_granularity"),
|
|
690
667
|
"status": feat.get("status"),
|
|
691
668
|
})
|
|
692
669
|
|
|
@@ -695,7 +672,6 @@ def generate_summary_json(data):
|
|
|
695
672
|
"features": feature_summaries,
|
|
696
673
|
"stats": {
|
|
697
674
|
"total_features": len(features),
|
|
698
|
-
"total_sub_features": total_sub,
|
|
699
675
|
"complexity_distribution": complexity_dist,
|
|
700
676
|
"max_dependency_depth": max_depth,
|
|
701
677
|
"has_cycles": has_cycles,
|
|
@@ -62,11 +62,11 @@ In an ordinary successful flow, `.prizmkit/plans/refactor-list.draft.json` is in
|
|
|
62
62
|
|
|
63
63
|
Every new or changed refactor item is an executable contract for a fresh AI session that has never seen the planning conversation. Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Use the existing fields correctly:
|
|
64
64
|
|
|
65
|
-
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.
|
|
65
|
+
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. AI rewrite is allowed; dropping a confirmed item is not. There is no word-count upper limit and no acceptance-criteria count upper limit.
|
|
66
66
|
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.
|
|
67
67
|
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.
|
|
68
68
|
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.
|
|
69
|
-
5. **Item isolation**: Each
|
|
69
|
+
5. **Item isolation**: Each written task contract and its supplementary evidence contain only relevant goals, paths, constraints, desired end state, and preservation evidence. Isolation does not mean split by module or directory. **Domain grouping**: Group by contract-bounded capability — shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract; independently shippable is not a split reason.
|
|
70
70
|
|
|
71
71
|
### Artifact-Wide AI Readability
|
|
72
72
|
|
|
@@ -389,7 +389,7 @@ Set behavior-preservation and testing expectations for each refactor item.
|
|
|
389
389
|
|
|
390
390
|
## Fast Path
|
|
391
391
|
|
|
392
|
-
For simple refactoring with minimal scope (1-2 items, low/medium complexity,
|
|
392
|
+
For simple refactoring with minimal scope (1-2 items, low/medium complexity, one contract-bounded capability, existing test coverage). Read `${SKILL_DIR}/references/fast-path.md` for eligibility criteria, full workflow (including AskUserQuestion format), conditions NOT to use, and an example session.
|
|
393
393
|
|
|
394
394
|
## Browser Verification
|
|
395
395
|
|
|
@@ -6,25 +6,26 @@ This guide provides structured patterns, decision matrices, and templates for de
|
|
|
6
6
|
|
|
7
7
|
## 1. Identifying Refactoring Boundaries
|
|
8
8
|
|
|
9
|
-
Refactoring boundaries define where one refactor item ends and another begins.
|
|
9
|
+
Refactoring boundaries define where one refactor item ends and another begins. Group by **contract-bounded capability**: shared domain objects, state machine, invariants, public API, and error semantics. That grouping is not the same module, directory, or written task contract. Independently shippable is not a split reason.
|
|
10
10
|
|
|
11
11
|
### Boundary Heuristics
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
|
16
|
-
|
|
17
|
-
| Different
|
|
18
|
-
| Different
|
|
19
|
-
|
|
|
13
|
+
These signals help assess coupling, risk, and verification depth. They do not by themselves create extra top-level items.
|
|
14
|
+
|
|
15
|
+
| Signal | What it tells you | Do not treat as |
|
|
16
|
+
|--------|-------------------|-----------------|
|
|
17
|
+
| Different files/modules | Blast radius and complexity **label** | Automatic extra list items |
|
|
18
|
+
| Different refactoring operations | Work mix inside one capability | A required split |
|
|
19
|
+
| Different risk levels | Test and review depth | A required split of one capability |
|
|
20
|
+
| Different test suites affected | Verification surface | A required split |
|
|
21
|
+
| Sequential dependency | Ordering inside or across capabilities | A split of one shared capability |
|
|
20
22
|
|
|
21
23
|
### Rules for Setting Boundaries
|
|
22
24
|
|
|
23
|
-
1. **
|
|
24
|
-
2. **
|
|
25
|
-
3. **
|
|
26
|
-
4. **
|
|
27
|
-
5. **If behavior preservation requires different strategies for different parts**, split into separate items with appropriate strategies.
|
|
25
|
+
1. **Prefer contract-bounded grouping.** Independently shippable is not a split reason. Directory and module names are clues only. A rename and a structural extraction stay one item when they share one contract-bounded capability and must land in one existing headless session.
|
|
26
|
+
2. **Each remaining top-level item should be independently testable.** After completing item R-001, all tests should pass before starting R-002.
|
|
27
|
+
3. **File count is a complexity label, not a split reason.** There is no word-count upper limit and no acceptance-criteria count upper limit.
|
|
28
|
+
4. **Split into additional top-level items only when implementation plus verification cannot finish in one existing headless session**, typically after two or more heavy capability seams, or when behavior preservation truly requires different strategies that cannot share one contract.
|
|
28
29
|
|
|
29
30
|
---
|
|
30
31
|
|
|
@@ -40,7 +41,7 @@ Refactor item descriptions are the primary input for autonomous pipeline session
|
|
|
40
41
|
| medium | 15 | 50 |
|
|
41
42
|
| high | 15 | 80 |
|
|
42
43
|
|
|
43
|
-
Below 15 words is a validation error. Below the threshold triggers a warning.
|
|
44
|
+
Below 15 words is a validation error. Below the threshold triggers a warning. There is no word-count upper limit and no acceptance-criteria count upper limit. AI rewrite is allowed; dropping a confirmed item is not.
|
|
44
45
|
|
|
45
46
|
### What to Include
|
|
46
47
|
|
|
@@ -267,7 +268,7 @@ Refactoring acceptance criteria focus on structural improvement AND behavior pre
|
|
|
267
268
|
1. **Always include "all existing tests pass"** — this is the fundamental refactoring invariant.
|
|
268
269
|
2. **Be specific about structural outcomes** — "files are organized by feature" is vague; "auth files are in src/features/auth/" is concrete.
|
|
269
270
|
3. **Include negative criteria** — "no circular dependencies", "no dead code", "no duplicated logic".
|
|
270
|
-
4. **Keep
|
|
271
|
+
4. **Keep every confirmed criterion.** There is no acceptance-criteria count upper limit. Do not drop confirmed preservation evidence to stay under a count.
|
|
271
272
|
|
|
272
273
|
---
|
|
273
274
|
|
|
@@ -283,10 +284,8 @@ Refactoring acceptance criteria focus on structural improvement AND behavior pre
|
|
|
283
284
|
|
|
284
285
|
**Rule**: Take the highest individual factor as the overall complexity. When in doubt, estimate higher.
|
|
285
286
|
|
|
286
|
-
### Complexity
|
|
287
|
+
### Complexity Labeling Notes
|
|
288
|
+
|
|
289
|
+
File count, module count, and acceptance-criteria count may raise the complexity **label**. They are not automatic split reasons. Independently shippable is not a split reason. Group by contract-bounded capability.
|
|
287
290
|
|
|
288
|
-
-
|
|
289
|
-
- Item requires changes to both test files and source files in non-trivial ways
|
|
290
|
-
- Item involves both structural change AND pattern migration
|
|
291
|
-
- Item has more than 6 acceptance criteria
|
|
292
|
-
- Item's description exceeds 100 words (suggests multiple operations combined)
|
|
291
|
+
Split into additional top-level items only when implementation plus verification cannot finish in one existing headless session, or when a necessary atomic migration would be broken by a split.
|
|
@@ -5,7 +5,7 @@ For simple refactoring with minimal scope.
|
|
|
5
5
|
## Eligibility Criteria (ALL must apply)
|
|
6
6
|
- 1-2 refactor items only
|
|
7
7
|
- Complexity: `low` or `medium` for all items
|
|
8
|
-
-
|
|
8
|
+
- The confirmed scope is one contract-bounded capability, or a user-explicit tiny slice of one; module and directory names do not decide eligibility
|
|
9
9
|
- Well-known refactoring pattern (rename, extract method/class, inline)
|
|
10
10
|
- Existing test coverage for target area
|
|
11
11
|
|
|
@@ -42,15 +42,14 @@ For simple refactoring with minimal scope.
|
|
|
42
42
|
## When NOT to Use Fast Path
|
|
43
43
|
- More than 2 refactor items
|
|
44
44
|
- Any item with `high` complexity
|
|
45
|
-
-
|
|
46
|
-
- Architecture migration patterns (Format C goals)
|
|
45
|
+
- Work that spans two contract-bounded capabilities or a confirmed architecture migration (Format C goals)
|
|
47
46
|
- No existing test coverage for target area
|
|
48
47
|
|
|
49
48
|
## Example Fast Path Session
|
|
50
49
|
```
|
|
51
50
|
User: "Rename the auth middleware function from checkAuth to requireAuth everywhere."
|
|
52
|
-
AI: [Detects simple rename,
|
|
53
|
-
AI: [Qualifies for fast path: 1 item, low complexity,
|
|
51
|
+
AI: [Detects simple rename, one contract-bounded capability]
|
|
52
|
+
AI: [Qualifies for fast path: 1 item, low complexity, one capability]
|
|
54
53
|
AI: [Uses AskUserQuestion with options: "Fast-path", "Full workflow"]
|
|
55
54
|
User: [Selects "Fast-path"]
|
|
56
55
|
AI: "Drafting R-001..."
|
|
@@ -46,6 +46,9 @@ For every reviewed refactor entry, check:
|
|
|
46
46
|
- Task-scoped `user_context` isolation: no unrelated sibling refactor goals, target files, constraints, desired end states, or supplementary materials; shared context appears on multiple items only when explicitly global
|
|
47
47
|
- Purpose-tagged stable code, configuration, machine-consumed interface, and URL targets; transient non-code planning/evidence paths are replaced by inline task-relevant decisions and excerpts, and large materials are bounded rather than injected in full
|
|
48
48
|
- Priority/complexity calibration: every reviewed refactor has short priority and complexity rationales, medium/low assignments are allowed when criteria fit, and high/high is not used merely because the work is cleanup, framework-related, multi-file, or user-requested
|
|
49
|
+
- Domain cohesion: same contract-bounded capability stays one top-level item; independently shippable is not a split reason; same-domain over-split is `NEEDS_FIXES` unless one existing headless session cannot finish
|
|
50
|
+
- Injected-field fidelity: confirmed structure, scope, preservation, and completion evidence are in `description` and `acceptance_criteria`; AI rewrite is allowed; dropping a confirmed item is not
|
|
51
|
+
- Size: there is no word-count upper limit and no acceptance-criteria count upper limit
|
|
49
52
|
|
|
50
53
|
## Headless Context Completeness Gate
|
|
51
54
|
|
|
@@ -9,7 +9,7 @@ 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 only the atomic operations necessary for the confirmed structural outcome; map each operation to a goal, behavior invariant, existing contract, or evidenced risk
|
|
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. Group by contract-bounded capability (shared domain objects, state machine, invariants, public API, and error semantics; not the same module, directory, or written task contract); independently shippable is not a split reason.
|
|
13
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
|
|
@@ -84,10 +84,10 @@ Use file counts as an initial heuristic, then adjust from verified public contra
|
|
|
84
84
|
|
|
85
85
|
| Affected Files | Impact Level | Planning Implication |
|
|
86
86
|
|---------------|-------------|---------------------|
|
|
87
|
-
| 1-3 | Low |
|
|
88
|
-
| 4-8 | Medium |
|
|
89
|
-
| 9-15 | High |
|
|
90
|
-
| 16+ | Very High |
|
|
87
|
+
| 1-3 | Low | Complexity/risk label; still one item when it is one contract-bounded capability |
|
|
88
|
+
| 4-8 | Medium | Raise complexity label and verification depth; do not add items solely for file count |
|
|
89
|
+
| 9-15 | High | Stronger tests and dependency tracing; keep one item unless an existing headless session cannot finish |
|
|
90
|
+
| 16+ | Very High | Session-overflow split at capability seams only; file count is not a split reason |
|
|
91
91
|
|
|
92
92
|
### Dependency Graph Analysis
|
|
93
93
|
|
|
@@ -164,8 +164,8 @@ Aggregate item risks to assess the plan:
|
|
|
164
164
|
|-----------|----------|
|
|
165
165
|
| Low | Standard test-gate, proceed normally |
|
|
166
166
|
| Medium | Ensure snapshot comparison, add extra acceptance criteria |
|
|
167
|
-
| High | Require
|
|
168
|
-
| Very High | Recommend writing comprehensive tests before refactoring
|
|
167
|
+
| High | Require stronger tests first; do not split a contract-bounded capability solely because risk is high |
|
|
168
|
+
| Very High | Recommend writing comprehensive tests before refactoring; split only when one existing headless session cannot finish |
|
|
169
169
|
|
|
170
170
|
---
|
|
171
171
|
|
|
@@ -175,18 +175,21 @@ Aggregate item risks to assess the plan:
|
|
|
175
175
|
|
|
176
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:
|
|
177
177
|
|
|
178
|
-
1. **Item count exceeds 8**: More than 8 items in a single plan increases coordination risk. Split into logical phases.
|
|
179
|
-
2. **
|
|
180
|
-
3. **Risk accumulates**: If items
|
|
181
|
-
4. **Cross-module
|
|
182
|
-
5. **Different preservation strategies
|
|
178
|
+
1. **Item count exceeds 8**: More than 8 items in a single plan increases coordination risk. Split into logical phases only when that is a different contract-bounded capability or an existing headless session cannot finish.
|
|
179
|
+
2. **Existing-session overflow**: Split at capability seams only when implementation plus verification cannot finish in one existing headless session.
|
|
180
|
+
3. **Risk accumulates**: If early items must be proven before a later high-risk seam, keep them as top-level items only when they do not share one contract-bounded capability that would otherwise drift.
|
|
181
|
+
4. **Cross-module work in one contract-bounded capability stays one item.** Independently shippable is not a split reason.
|
|
182
|
+
5. **Different preservation strategies**: Split only when those strategies cannot share one contract and one existing headless session.
|
|
183
183
|
|
|
184
184
|
### How to Split
|
|
185
185
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
186
|
+
When a split is justified by the heuristics above, create additional **top-level** items at capability seams, each with a complete injected contract:
|
|
187
|
+
|
|
188
|
+
1. **By contract-bounded capability**, not by directory or module name alone
|
|
189
|
+
2. **By existing-session overflow**, when one headless session cannot finish implementation plus verification
|
|
190
|
+
3. **By true dependency layer** only when later work cannot share the earlier item's contracts without drift
|
|
191
|
+
|
|
192
|
+
Do not open a new list merely because files live in different modules. Independently shippable is not a split reason.
|
|
190
193
|
|
|
191
194
|
### Merging Split Plans
|
|
192
195
|
|