prizmkit 1.1.178 → 1.1.180
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/rules/prizm/prizm-progressive-loading.md +1 -0
- package/bundled/skills/_metadata.json +1 -1
- package/bundled/skills/app-planner/SKILL.md +7 -7
- package/bundled/skills/app-planner/references/generated-plan-review.md +6 -6
- package/bundled/skills/app-planner/references/rules/frontend/derivation-rules.md +86 -18
- package/bundled/skills/app-planner/references/rules/frontend/fixed-rules.md +122 -1
- package/bundled/skills/app-planner/references/rules/frontend/question-bank.md +2 -2
- package/bundled/skills/app-planner/references/rules/frontend/question-manifest.json +4 -4
- package/bundled/skills/app-planner/references/rules/frontend/template.md +40 -1
- package/bundled/skills/app-planner/references/rules-configuration.md +8 -3
- 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 +4 -4
- package/bundled/skills/feature-planner/assets/planning-guide.md +21 -45
- 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/new-project-planning.md +7 -6
- package/bundled/skills/feature-planner/scripts/validate-and-generate.py +13 -8
- package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
- package/bundled/skills/prizmkit-init/SKILL.md +2 -0
- package/bundled/skills/prizmkit-plan/SKILL.md +2 -1
- package/bundled/skills/prizmkit-plan/references/verification-checklist.md +1 -0
- package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +11 -0
- package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -0
- package/bundled/skills/prizmkit-prizm-docs/references/op-rebuild.md +1 -1
- package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
- package/bundled/skills/prizmkit-retrospective/references/structural-sync-steps.md +1 -1
- 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/bundled/templates/project-memory-template.md +1 -0
- package/package.json +1 -1
|
@@ -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
|
|
|
@@ -6,6 +6,7 @@ This project uses PrizmKit with the Prizm documentation system for AI-optimized
|
|
|
6
6
|
### Progressive Loading Protocol
|
|
7
7
|
- ON SESSION START: Read exact `.prizmkit/prizm-docs/root.prizm` first when it exists; it alone is L0.
|
|
8
8
|
- ON TASK: Read only relevant direct-child L1 documents (`.prizmkit/prizm-docs/<module>.prizm`) selected through MODULE_INDEX or MODULE_GROUPS pointers.
|
|
9
|
+
- LAYER_RULES: If the current task lands on frontend, backend, database, or mobile, Read `.prizmkit/rules/<layer>-rules.md` when that exact convention path exists. Skip a missing file without blocking. Never load all four files by default. If a task spans two layers, read both existing files. Map browser UI work to frontend, service or API work to backend, schema migration or ORM work to database, and iOS, Android, React Native, or Flutter work to mobile. Discover by exact path Read; do not depend on git tracking or glob. When a layer-rules sentence conflicts with current L2 `.prizm` facts, committed OpenAPI or other contract sources, or project instruction conventions, those current sources win without a clarification pause. L0 `RULES:` MUST/NEVER remain authoritative for that key.
|
|
9
10
|
- ON FILE EDIT: Read the complete relevant nested L2 and complete parent/child documents needed to resolve its SUBDIRS or DETAILS pointer. Grep-only fragments are insufficient modification context.
|
|
10
11
|
- IF L2 IS ABSENT: Inspect bounded target source and narrowly implicated contracts without creating a placeholder; documentation creation belongs to Retrospective or explicit repair.
|
|
11
12
|
- NEVER load all `.prizm` docs at once, load unrelated modules, or create L3.
|