prizmkit 1.1.190 → 1.1.192
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/bin/create-prizmkit.js +4 -4
- package/bundled/VERSION.json +3 -3
- package/bundled/adapters/antigravity/assets/prizmkit-hook.cjs +150 -0
- package/bundled/adapters/antigravity/hooks-adapter.js +195 -0
- package/bundled/adapters/antigravity/paths.js +14 -0
- package/bundled/adapters/antigravity/rules-adapter.js +54 -0
- package/bundled/adapters/antigravity/skill-adapter.js +38 -0
- package/bundled/adapters/codex/skill-adapter.js +28 -8
- package/bundled/adapters/cursor/skill-adapter.js +13 -4
- package/bundled/adapters/pi/skill-adapter.js +28 -7
- package/bundled/dev-pipeline/.env.example +4 -12
- package/bundled/dev-pipeline/README.md +21 -15
- package/bundled/dev-pipeline/assets/skill-subagent-integration.md +3 -6
- package/bundled/dev-pipeline/prizmkit_runtime/atomic_io.py +48 -0
- package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +66 -23
- package/bundled/dev-pipeline/prizmkit_runtime/cli.py +10 -7
- package/bundled/dev-pipeline/prizmkit_runtime/commands.py +2 -21
- package/bundled/dev-pipeline/prizmkit_runtime/config.py +29 -70
- package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +125 -67
- package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +89 -442
- package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +93 -49
- package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -3
- package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
- package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +49 -18
- package/bundled/dev-pipeline/prizmkit_runtime/processes.py +206 -151
- package/bundled/dev-pipeline/prizmkit_runtime/reset.py +2 -23
- package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +15 -134
- package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
- package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +68 -83
- package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
- package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -29
- package/bundled/dev-pipeline/prizmkit_runtime/runner_prompts.py +0 -2
- package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py +7 -2
- package/bundled/dev-pipeline/prizmkit_runtime/runners.py +282 -217
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +124 -122
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
- package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +369 -154
- package/bundled/dev-pipeline/prizmkit_runtime/status.py +3 -3
- package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2780 -0
- package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -101
- package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
- package/bundled/dev-pipeline/scripts/check-session-status.py +43 -19
- package/bundled/dev-pipeline/scripts/continuation.py +6 -4
- package/bundled/dev-pipeline/scripts/detect-stuck.py +28 -28
- package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +7 -2
- package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +7 -2
- package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
- package/bundled/dev-pipeline/scripts/init-change-artifact.py +8 -2
- package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
- package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2328
- package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
- package/bundled/dev-pipeline/scripts/prompt_framework.py +56 -9
- package/bundled/dev-pipeline/scripts/status_common.py +591 -0
- package/bundled/dev-pipeline/scripts/update-bug-status.py +85 -463
- package/bundled/dev-pipeline/scripts/update-checkpoint.py +227 -65
- package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
- package/bundled/dev-pipeline/scripts/utils.py +10 -15
- package/bundled/dev-pipeline/templates/bootstrap-tier3.md +4 -4
- package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
- package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +1 -1
- package/bundled/dev-pipeline/templates/sections/artifact-manifest.md +1 -1
- package/bundled/dev-pipeline/templates/sections/bugfix-phase-manual-verification.md +1 -1
- package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md +1 -1
- package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md +2 -1
- package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +1 -1
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +2 -2
- package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +2 -2
- package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md +2 -1
- package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -1
- package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +3 -6
- package/bundled/dev-pipeline/templates/session-status-schema.json +2 -5
- package/bundled/dev-pipeline/tests/_helpers.py +418 -0
- package/bundled/dev-pipeline/tests/conftest.py +45 -1
- package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +1 -0
- package/bundled/dev-pipeline/tests/test_auto_skip.py +4 -69
- package/bundled/dev-pipeline/tests/test_checkpoint_state.py +126 -1
- package/bundled/dev-pipeline/tests/test_daemon_and_scripts.py +257 -0
- package/bundled/dev-pipeline/tests/test_e2e_pipeline_run.py +500 -0
- package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +59 -117
- package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +12 -10
- package/bundled/dev-pipeline/tests/test_python_runner_parity.py +561 -3094
- package/bundled/dev-pipeline/tests/test_recovery_workflow.py +7 -8
- package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -1
- package/bundled/dev-pipeline/tests/test_reset_modes.py +15 -27
- package/bundled/dev-pipeline/tests/test_reset_preserve.py +54 -139
- package/bundled/dev-pipeline/tests/test_runner_bookkeeping.py +766 -0
- package/bundled/dev-pipeline/tests/test_runner_lifecycle.py +1257 -0
- package/bundled/dev-pipeline/tests/test_runtime_helper.py +97 -20
- package/bundled/dev-pipeline/tests/test_session_launch.py +1101 -0
- package/bundled/dev-pipeline/tests/test_stream_progress.py +585 -0
- package/bundled/dev-pipeline/tests/test_unified_cli.py +490 -2006
- package/bundled/dev-pipeline/tests/test_utils.py +3 -3
- package/bundled/rules/USAGE.md +1 -0
- package/bundled/skills/_metadata.json +9 -63
- package/bundled/skills/app-planner/SKILL.md +32 -303
- package/bundled/skills/app-planner/references/app-design-guide.md +0 -4
- package/bundled/skills/app-planner/references/generated-plan-review.md +2 -1
- package/bundled/skills/app-planner/references/project-brief-guide.md +14 -0
- package/bundled/skills/app-planner/references/project-conventions-discovery.md +4 -6
- package/bundled/skills/app-planner/references/project-state-detection.md +2 -3
- package/bundled/skills/bug-fix-workflow/SKILL.md +1 -2
- package/bundled/skills/bug-fix-workflow/references/bug-diagnosis.md +4 -7
- package/bundled/skills/bug-planner/SKILL.md +54 -435
- package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -2
- package/bundled/skills/bug-planner/references/input-formats.md +32 -0
- package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +4 -6
- package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +4 -28
- package/bundled/skills/feature-pipeline-launcher/SKILL.md +4 -6
- package/bundled/skills/feature-pipeline-launcher/references/configuration.md +4 -28
- package/bundled/skills/feature-planner/SKILL.md +60 -439
- package/bundled/skills/feature-planner/assets/planning-guide.md +1 -1
- package/bundled/skills/feature-planner/references/completeness-review.md +34 -0
- package/bundled/skills/feature-planner/references/decomposition-patterns.md +2 -2
- package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
- package/bundled/skills/feature-planner/references/generated-plan-review.md +3 -2
- package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -1
- package/bundled/skills/feature-workflow/SKILL.md +1 -2
- package/bundled/skills/prizmkit/SKILL.md +7 -1
- package/bundled/skills/prizmkit-code-review/SKILL.md +14 -6
- package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +7 -4
- package/bundled/skills/prizmkit-code-review/references/review-report-template.md +16 -0
- package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +58 -20
- package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
- package/bundled/skills/prizmkit-init/SKILL.md +25 -128
- package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
- package/bundled/skills/prizmkit-init/references/config-schema.md +2 -2
- package/bundled/skills/prizmkit-plan/SKILL.md +6 -8
- package/bundled/skills/prizmkit-plan/references/clarify-guide.md +1 -1
- package/bundled/skills/prizmkit-plan/references/independent-plan-review.md +5 -2
- package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +6 -5
- package/bundled/skills/prizmkit-prizm-docs/SKILL.md +1 -13
- package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +1 -1
- package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -1
- package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
- package/bundled/skills/prizmkit-retrospective/SKILL.md +6 -4
- package/bundled/skills/prizmkit-test/SKILL.md +25 -133
- package/bundled/skills/prizmkit-test/references/independent-test-review.md +5 -2
- package/bundled/skills/prizmkit-test/references/test-coverage-model.md +6 -0
- package/bundled/skills/prizmkit-workflow/SKILL.md +2 -3
- package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +4 -3
- package/bundled/skills/recovery-workflow/SKILL.md +7 -7
- package/bundled/skills/recovery-workflow/evals/evals.json +1 -1
- package/bundled/skills/recovery-workflow/references/detection.md +1 -3
- package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +0 -6
- package/bundled/templates/project-memory-template.md +1 -2
- package/package.json +1 -1
- package/src/ai-cli-launch.js +1 -1
- package/src/clean.js +40 -4
- package/src/config.js +64 -4
- package/src/detect-platform.js +10 -6
- package/src/external-skills.js +2 -2
- package/src/index.js +1 -0
- package/src/manifest.js +1 -1
- package/src/platforms.js +6 -2
- package/src/prompts.js +11 -3
- package/src/scaffold.js +87 -11
- package/src/upgrade.js +9 -3
- package/bundled/dev-pipeline/SCHEMA_ANALYSIS.md +0 -53
- package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +0 -649
- package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +0 -463
- package/bundled/dev-pipeline/scripts/update-refactor-status.py +0 -1512
- package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +0 -240
- package/bundled/dev-pipeline/templates/refactor-list-schema.json +0 -266
- package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md +0 -15
- package/bundled/dev-pipeline/templates/sections/refactor-mission.md +0 -9
- package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md +0 -24
- package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md +0 -16
- package/bundled/dev-pipeline/templates/sections/refactor-phase-init.md +0 -9
- package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md +0 -22
- package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md +0 -19
- package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md +0 -24
- package/bundled/dev-pipeline/templates/sections/refactor-reminders.md +0 -12
- package/bundled/dev-pipeline/templates/sections/refactor-session-context.md +0 -6
- package/bundled/dev-pipeline/templates/sections/refactor-task-contract.md +0 -52
- package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
- package/bundled/skills/feature-planner/assets/evaluation-guide.md +0 -44
- package/bundled/skills/refactor-pipeline-launcher/SKILL.md +0 -219
- package/bundled/skills/refactor-pipeline-launcher/references/configuration.md +0 -78
- package/bundled/skills/refactor-planner/SKILL.md +0 -467
- package/bundled/skills/refactor-planner/assets/planning-guide.md +0 -291
- package/bundled/skills/refactor-planner/references/behavior-preservation.md +0 -187
- package/bundled/skills/refactor-planner/references/error-recovery.md +0 -45
- package/bundled/skills/refactor-planner/references/fast-path.md +0 -59
- package/bundled/skills/refactor-planner/references/generated-plan-review.md +0 -107
- package/bundled/skills/refactor-planner/references/planning-phases.md +0 -172
- package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +0 -230
- package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +0 -1120
- package/bundled/skills/refactor-workflow/SKILL.md +0 -205
|
@@ -1,467 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: "refactor-planner"
|
|
3
|
-
description: "Interactive refactoring planner. Understands refactoring intent through dialogue, analyzes current code structure, identifies refactoring targets, decomposes large refactors or code migrations, and produces validated .prizmkit/plans/refactor-list.json for dev-pipeline execution. Use whenever users discuss refactoring planning, code restructuring scope, code migration planning, or preparing .prizmkit/plans/refactor-list.json."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# refactor planner
|
|
7
|
-
|
|
8
|
-
Plan executable refactoring items for later autonomous dev-pipeline execution. This skill creates or updates planning artifacts only:
|
|
9
|
-
- **Scope Assessment**: analyze current code structure and identify refactoring targets
|
|
10
|
-
- **Item Decomposition**: break refactoring goals into well-ordered, behavior-preserving items
|
|
11
|
-
|
|
12
|
-
Always produce a validated `.prizmkit/plans/refactor-list.json` that conforms to `dev-pipeline-refactor-list-v1`.
|
|
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
|
-
|
|
23
|
-
## Invocation Commitment (Hard Rule)
|
|
24
|
-
|
|
25
|
-
**When the user invokes `/refactor-planner`, you MUST execute the refactor-planner workflow.** You must NEVER:
|
|
26
|
-
- Decide on the user's behalf that the task "doesn't need refactor-planner"
|
|
27
|
-
- Skip refactor-planner to jump directly to refactor-workflow or any other skill
|
|
28
|
-
- Bypass the interactive phases because you judge the task to be "simple" or "obvious"
|
|
29
|
-
|
|
30
|
-
If you believe the task is better suited for a different workflow (e.g., single-file refactor via `/refactor-workflow`), you MUST:
|
|
31
|
-
1. **Explain why** you think a different path is more appropriate
|
|
32
|
-
2. **Ask the user explicitly** whether they want to switch or continue with refactor-planner
|
|
33
|
-
3. **Only switch if the user confirms** — otherwise proceed with refactor-planner as invoked
|
|
34
|
-
|
|
35
|
-
The user chose this skill intentionally. Respect that choice.
|
|
36
|
-
|
|
37
|
-
## Scope Boundary (Hard Rule)
|
|
38
|
-
|
|
39
|
-
**This skill is PLANNING ONLY.** It may analyze code for planning evidence and create, append, validate, and review refactor planning artifacts, but it must never perform the refactor or start execution. You must NEVER:
|
|
40
|
-
- Create, modify, or delete source code files (*.js, *.ts, *.py, *.go, *.html, *.css, etc.)
|
|
41
|
-
- Execute refactoring operations (rename, move, extract, etc.)
|
|
42
|
-
- Run build/install/test commands
|
|
43
|
-
- Execute any implementation action beyond writing `.prizmkit/plans/refactor-list.json`
|
|
44
|
-
|
|
45
|
-
**Your ONLY writable outputs are:**
|
|
46
|
-
1. `.prizmkit/plans/refactor-list.json` (`.prizmkit/plans/`)
|
|
47
|
-
2. Planner-owned draft state in `.prizmkit/plans/` (e.g., `refactor-list.draft.json`) while it is required for deterministic writing, review repair, or explicit recovery
|
|
48
|
-
|
|
49
|
-
**After planning is complete**, you MUST:
|
|
50
|
-
1. Present the summary and recommended next step
|
|
51
|
-
2. **Ask the user explicitly** whether they want to proceed to execution
|
|
52
|
-
3. If the user agrees → recommend invoking `refactor-pipeline-launcher` (do NOT execute it yourself)
|
|
53
|
-
4. If the user wants to adjust → continue refining `.prizmkit/plans/refactor-list.json`
|
|
54
|
-
5. **NEVER auto-execute** the pipeline, launcher, composite workflow, or any implementation step
|
|
55
|
-
6. Return the validated refactor list to the caller; only `refactor-pipeline-launcher` prepares the runtime command
|
|
56
|
-
|
|
57
|
-
## Draft Lifecycle (Hard Rule)
|
|
58
|
-
|
|
59
|
-
In an ordinary successful flow, `.prizmkit/plans/refactor-list.draft.json` is a private reasoning workspace: never presented as a deliverable, never given its own approval round, never retained after the batch lands. Build the batch there, validate it there, and run the entire Local Generated-Plan Review against it; the final list is written exactly once, after that review returns `PASS`, by a single `append` (existing list) or `generate` (new list). Then delete the draft immediately and report `Draft cleanup: removed`. A batch lost before it lands is regenerated from the confirmed decisions rather than recovered. Conditions that must keep a draft — explicit draft-save, interruption, a writer-rejected insert, cleanup failure — are defined in `${SKILL_DIR}/references/error-recovery.md`, and any retained path is named in the terminal report. For later adjustments, recreate only the minimum source draft from confirmed in-memory entries or exact-ID `show`; modifying entries this session did not create is the one case that still uses `append --replace-tail` for the exact current suffix.
|
|
60
|
-
|
|
61
|
-
## Fresh-Session Task Contract (Hard Rule)
|
|
62
|
-
|
|
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
|
-
|
|
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
|
-
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
|
-
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
|
-
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 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
|
-
|
|
71
|
-
### Artifact-Wide AI Readability
|
|
72
|
-
|
|
73
|
-
- 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, scope explanations, complexity/priority rationale, `behavior_preservation`, `completion_notes`, acceptance criteria, `user_context`, verification goals, comments, appendices, and parentheticals.
|
|
74
|
-
- Machine metadata such as schema markers, stable IDs, statuses, enums, and timestamps is exempt. Natural-language metadata is not exempt.
|
|
75
|
-
- 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.
|
|
76
|
-
- `user_context` may hold independently intelligible evidence, not transcript fragments. Rewrite every confirmed turn into direct current/target architecture, scope, constraints, rationale, preservation, or verification evidence before generation.
|
|
77
|
-
|
|
78
|
-
### Conversational Context Normalization
|
|
79
|
-
|
|
80
|
-
- Never persist standalone option labels such as `A`, `B`, `C`, `方案A`, or `方案B` as execution context.
|
|
81
|
-
- Expand a selected option into complete meaning and preserve substantive user rationale and constraints in durable prose at matching detail.
|
|
82
|
-
- Do not emit transcript annotations such as `(original response: "...")` in final refactor artifacts. Bare option labels and relative shorthand are not independently intelligible and materially useful exact wording.
|
|
83
|
-
- Resolve `上面`, `这个`, `按推荐走`, `同前`, `继续这样`, `用刚才的方案`, `same as above`, or `go with your recommendation` only when there is one provable antecedent. Otherwise ask the user for clarification; never guess.
|
|
84
|
-
- Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization. Apply the concrete accepted recommendations, then omit the raw approval; never repeat it once per accepted recommendation.
|
|
85
|
-
- Do not present rejected architectures as active instructions; preserve one only when it defines a necessary non-goal or compatibility boundary. Retain exact user wording only when it is independently intelligible and materially useful.
|
|
86
|
-
|
|
87
|
-
### Reference Material Handling
|
|
88
|
-
|
|
89
|
-
- Every retained stable code, configuration, machine-consumed interface, or URL reference must be purpose-tagged: state why it is relevant and what the execution AI should inspect. This applies to paths and URLs in the task contract and `user_context`.
|
|
90
|
-
- Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`, uploaded-analysis paths, screenshot paths, or ad-hoc log paths in durable refactor contracts. Instead, copy or normalize the task-relevant content into `description` and `acceptance_criteria`; the item must not depend on that source file still existing.
|
|
91
|
-
- Good: `src/auth/validation.ts — inspect exported signatures and current error semantics before extracting middleware`; Bad: `src/auth/validation.ts` alone.
|
|
92
|
-
- For large materials, preserve purpose and only task-relevant exact excerpts, and move confirmed target architecture, scope boundaries, constraints, and preservation decisions into `description` and `acceptance_criteria`. Retain a location only when it is a stable execution-time source of truth.
|
|
93
|
-
- Embed complete large materials only when the execution session cannot access the source and all content is genuinely required.
|
|
94
|
-
|
|
95
|
-
### Good and Bad Normalization Examples
|
|
96
|
-
|
|
97
|
-
- Bad: `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation` stored as the target architecture.
|
|
98
|
-
- Bad: `Selected decision: extract auth validation (original response: "方案B")`; the annotation still requires an unseen option list.
|
|
99
|
-
- Good: `Selected decision: extract validation behind an auth-owned middleware interface while preserving all handler exports`.
|
|
100
|
-
- Good: `Selected decision: migrate imports in one compatibility-preserving phase and remove no public paths`.
|
|
101
|
-
- Bad: storing or repeating `全部按照推荐` / `所有问题都按你的推荐处理` as a preservation rule; it is conversational authorization.
|
|
102
|
-
- Bad: attaching a full architecture RFC or `.agents/brainstorm/refactor.md` path while saying only `apply this`. Good: copy the relevant architecture, scope, and preservation decisions into the item contract and omit the transient planning path.
|
|
103
|
-
|
|
104
|
-
**Multi-refactor isolation example:**
|
|
105
|
-
- User request includes: `Refactor A: extract auth validation into middleware`, `Refactor B: split dashboard chart utilities`, and `Shared: preserve all public APIs`.
|
|
106
|
-
- The auth item contract fully defines its current and target structure and includes only matching evidence plus the shared API constraint; it MUST NOT include chart-utility scope.
|
|
107
|
-
- The chart item contract fully defines its current and target structure and includes only matching evidence plus the shared API constraint; it MUST NOT include auth scope.
|
|
108
|
-
|
|
109
|
-
## When to Use
|
|
110
|
-
- "Plan refactoring", "Scope a restructuring"
|
|
111
|
-
- "Prepare .prizmkit/plans/refactor-list.json", "Prepare dev-pipeline input for refactoring"
|
|
112
|
-
- "Assess code for refactoring", "Identify refactoring targets"
|
|
113
|
-
- "Plan a code migration", "Decompose a large refactor"
|
|
114
|
-
|
|
115
|
-
Do NOT use this skill when the user wants to:
|
|
116
|
-
- Execute a single refactor directly (use `refactor-workflow`)
|
|
117
|
-
- Plan new features (use `feature-planner`)
|
|
118
|
-
- Fix bugs (use `bug-planner`)
|
|
119
|
-
|
|
120
|
-
## Resource Loading Rules (Mandatory)
|
|
121
|
-
|
|
122
|
-
1. **Read decomposition guide**:
|
|
123
|
-
- Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and description guidelines
|
|
124
|
-
|
|
125
|
-
2. **Read scope assessment reference**:
|
|
126
|
-
- Read `${SKILL_DIR}/references/refactor-scoping-guide.md` for scope classification and risk assessment
|
|
127
|
-
|
|
128
|
-
3. **Read behavior preservation reference**:
|
|
129
|
-
- Read `${SKILL_DIR}/references/behavior-preservation.md` for preservation strategy selection
|
|
130
|
-
|
|
131
|
-
4. **Load on-demand references when triggered**:
|
|
132
|
-
- Validation errors or interrupted session -> see the "Error Recovery & Resume" section below
|
|
133
|
-
|
|
134
|
-
5. **Always validate output via script**:
|
|
135
|
-
- Run:
|
|
136
|
-
```bash
|
|
137
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input <output-path>
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
6. **Use script output as source of truth**:
|
|
141
|
-
- If validation fails, **MUST** fix and re-run until pass
|
|
142
|
-
|
|
143
|
-
## Prerequisites
|
|
144
|
-
|
|
145
|
-
Before questions, check optional context files (never block if absent):
|
|
146
|
-
- `.prizmkit/prizm-docs/root.prizm` (architecture/project context)
|
|
147
|
-
- `.prizmkit/config.json` (existing stack preferences and detected tech stack)
|
|
148
|
-
- Existing test suite (critical for behavior preservation assessment)
|
|
149
|
-
- Existing `.prizmkit/plans/refactor-list.json` (if appending additional items; inspect it only through the bounded commands below)
|
|
150
|
-
- If `.prizmkit/prizm-docs/root.prizm` is absent and the project has existing source code, scan the directory structure:
|
|
151
|
-
```bash
|
|
152
|
-
find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/__pycache__/*' -not -path '*/vendor/*' | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
**Test suite detection:**
|
|
156
|
-
- Scan for test runner config files (`jest.config.*`, `vitest.config.*`, `pytest.ini`, `.mocharc.*`, `karma.conf.*`)
|
|
157
|
-
- If no test suite detected, WARN: "No test suite found. Behavior preservation will rely on manual verification. Consider writing tests before refactoring."
|
|
158
|
-
- Record test suite status in planning context for downstream use
|
|
159
|
-
|
|
160
|
-
## Bounded Existing-List Context (Hard Rule)
|
|
161
|
-
|
|
162
|
-
For any flow that appends to an existing `.prizmkit/plans/refactor-list.json`, NEVER read the complete historical list into AI context and NEVER perform default full-history keyword search.
|
|
163
|
-
|
|
164
|
-
1. Load only bounded project and recent-task context:
|
|
165
|
-
```bash
|
|
166
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py context --input .prizmkit/plans/refactor-list.json
|
|
167
|
-
```
|
|
168
|
-
Consume only `project_name`, `project_description`, `global_context`, `task_count`, `next_id`, and exactly the five most recently appended top-level refactors as `{id, description}` pairs (or all available refactors when fewer than five exist).
|
|
169
|
-
2. Inspect those five pairs only for material continuation, duplication, conflict, a shared public behavior contract, or an execution prerequisite. Add no historical content by default. Chronology, broad module overlap, shared technology, reusable implementation ideas, or similar wording alone do not establish relevance.
|
|
170
|
-
3. When a material relationship exists, incorporate only the minimum exact information whose omission would make the new refactor's scope, behavior preservation, compatibility, acceptance criteria, or dependency ordering incorrect. Do not write vague text such as `related to R-123`, do not copy an entire historical description merely because it overlaps, and add an old ID to `dependencies` only when it is a real execution prerequisite.
|
|
171
|
-
4. Load a complete historical refactor only when the user explicitly identifies its ID for modification or detailed review, or a validation error identifies it:
|
|
172
|
-
```bash
|
|
173
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN
|
|
174
|
-
```
|
|
175
|
-
5. For append-only planning, write `.prizmkit/plans/refactor-list.draft.json` as an additions-only object with exactly one root field, `refactors`. The array must be non-empty; each item uses the unchanged final refactor-item schema, with required `id`, `title`, `description`, `scope`, `type`, `priority`, `complexity`, `behavior_preservation`, `dependencies`, and `acceptance_criteria`; `status` may be omitted and defaults to `pending`; all existing optional refactor fields remain allowed. Do not copy root metadata or historical refactors into this bounded private reasoning workspace, which is the review target rather than a deliverable.
|
|
176
|
-
6. After consequential decisions and the pre-generation gate pass, write the batch to the additions-only draft with the `context` IDs and check merge feasibility without writing:
|
|
177
|
-
```bash
|
|
178
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json --dry-run
|
|
179
|
-
```
|
|
180
|
-
Do not ask for separate user approval merely to promote the draft into the final list. The dry run applies the same base, exact-ID, dependency, and complete-DAG checks the real insert will, so a `PASS` review is a promise the insert keeps. Run the real `append` once, after §Local Generated-Plan Review Gate returns `PASS`, then follow §Draft Lifecycle. Existing `generate` remains the new-list/full-rewrite path.
|
|
181
|
-
|
|
182
|
-
## Operation Modes
|
|
183
|
-
|
|
184
|
-
### Mode A: Interactive (default)
|
|
185
|
-
Full Q&A -> code analysis -> item generation. Used when starting from scratch or exploring refactoring scope.
|
|
186
|
-
|
|
187
|
-
### Mode B: From Analysis
|
|
188
|
-
When an existing analysis report (e.g., `refactor-analysis.md`) is available, skip the analysis phase and proceed directly to item decomposition.
|
|
189
|
-
|
|
190
|
-
### Mode C: Validate
|
|
191
|
-
Validate an existing `.prizmkit/plans/refactor-list.json` without regenerating it:
|
|
192
|
-
```bash
|
|
193
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py validate --input .prizmkit/plans/refactor-list.json
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
### Mode D: Summary
|
|
197
|
-
Display a human-readable summary of an existing `.prizmkit/plans/refactor-list.json`:
|
|
198
|
-
- Item count, dependency graph, complexity distribution, behavior preservation strategies
|
|
199
|
-
|
|
200
|
-
## Interactive Mode — Core Workflow
|
|
201
|
-
|
|
202
|
-
Execute the planning workflow in conversation mode with mandatory checkpoints:
|
|
203
|
-
|
|
204
|
-
### Phase 1: Project Context
|
|
205
|
-
|
|
206
|
-
**Goal**: Understand the current codebase structure and tech stack.
|
|
207
|
-
|
|
208
|
-
1. Read `.prizmkit/prizm-docs/root.prizm` and the relevant module documents it points to
|
|
209
|
-
2. Read `.prizmkit/config.json` for tech stack info
|
|
210
|
-
3. Identify existing test suite and coverage
|
|
211
|
-
4. Summarize project context to the user: "Here's what I found about your project..."
|
|
212
|
-
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.
|
|
213
|
-
|
|
214
|
-
If the user has NOT provided any materials upfront, explicitly ask whether they have any supplementary materials for you to review before planning the refactoring:
|
|
215
|
-
> "Do you have any reference materials I should review before planning the refactoring? This can include:
|
|
216
|
-
> - **Code paths** — specific files or directories that are refactoring targets or dependencies
|
|
217
|
-
> - **Documents** — design docs, architecture proposals, refactoring RFCs, or technical debt analyses
|
|
218
|
-
> - **Knowledge docs** — `.prizmkit/prizm-docs/` files, README files, or internal wiki pages for the affected area
|
|
219
|
-
> - **Images** — architecture diagrams, dependency graphs, or whiteboard photos
|
|
220
|
-
> - **Web links** — reference implementations, design pattern articles, or migration guides
|
|
221
|
-
>
|
|
222
|
-
> If none, we'll proceed with what's available in the codebase."
|
|
223
|
-
|
|
224
|
-
If the user provides materials, require or infer only when unambiguous a refactor-specific purpose for each material; otherwise ask what the execution AI should inspect. Read/fetch the relevant material before Phase 2. For web links, retrieve 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 inject complete large materials merely to preserve them. This context is critical for understanding the target architecture and constraints.
|
|
225
|
-
|
|
226
|
-
**CHECKPOINT CP-RP-0**: Project context loaded, tech stack and test suite status known.
|
|
227
|
-
|
|
228
|
-
### Phase 2: Refactor Goal Collection
|
|
229
|
-
|
|
230
|
-
**Goal**: Through interactive dialogue, understand what the user wants to refactor and why.
|
|
231
|
-
|
|
232
|
-
Support 4 input formats (users may mix formats):
|
|
233
|
-
|
|
234
|
-
**Format A — Natural language**:
|
|
235
|
-
> "This module is too large and hard to maintain"
|
|
236
|
-
> "The auth logic is scattered across too many files"
|
|
237
|
-
|
|
238
|
-
**Format B — Code smell pointer**:
|
|
239
|
-
> "src/api/handler.js is 800 lines"
|
|
240
|
-
> "There are 5 files that all implement similar validation logic"
|
|
241
|
-
|
|
242
|
-
**Format C — Architecture migration**:
|
|
243
|
-
> "Convert callbacks to async/await"
|
|
244
|
-
> "Migrate from class components to hooks"
|
|
245
|
-
> "Move from monolith to modular architecture"
|
|
246
|
-
|
|
247
|
-
**Format D — Dependency decoupling**:
|
|
248
|
-
> "There's a circular dependency between auth and user modules"
|
|
249
|
-
> "The database layer is tightly coupled to the HTTP layer"
|
|
250
|
-
|
|
251
|
-
For each input, establish:
|
|
252
|
-
- The confirmed structural pain point and desired outcome.
|
|
253
|
-
- Evidence-backed target files, modules, patterns, consumers, and purpose-tagged inspection paths.
|
|
254
|
-
- Behavior invariants, public contracts, scope boundaries, and non-goals.
|
|
255
|
-
- Behavior-preservation and completion evidence.
|
|
256
|
-
- Motivation and constraints that determine whether a target architecture is necessary.
|
|
257
|
-
|
|
258
|
-
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.
|
|
259
|
-
|
|
260
|
-
**CHECKPOINT CP-RP-1**: All refactoring goals collected and understood.
|
|
261
|
-
|
|
262
|
-
### Phase 3: Code Analysis
|
|
263
|
-
|
|
264
|
-
**Goal**: Analyze the target code to inform item decomposition.
|
|
265
|
-
|
|
266
|
-
Run three parallel read-only analysis perspectives over the target files:
|
|
267
|
-
- **Structure perspective**: File inventory, dependency graph, module boundaries, public API surface
|
|
268
|
-
- **Quality perspective**: Code smells, complexity hotspots, duplication, coupling metrics
|
|
269
|
-
- **Test perspective**: Test coverage of target areas, existing test patterns, behavior contracts
|
|
270
|
-
|
|
271
|
-
Present consolidated findings:
|
|
272
|
-
```
|
|
273
|
-
## Code Analysis Results
|
|
274
|
-
|
|
275
|
-
### Structure
|
|
276
|
-
- [file inventory, dependency graph]
|
|
277
|
-
|
|
278
|
-
### Quality Issues
|
|
279
|
-
- [code smells, complexity hotspots, duplication]
|
|
280
|
-
|
|
281
|
-
### Test Coverage
|
|
282
|
-
- [test status for target areas]
|
|
283
|
-
- [behavior contracts that must be preserved]
|
|
284
|
-
|
|
285
|
-
### Recommended Decomposition
|
|
286
|
-
- [suggested refactoring order based on findings]
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
Ask: "Based on this analysis, here's how I'd recommend decomposing the refactoring. Does this align with your expectations?"
|
|
290
|
-
|
|
291
|
-
**CHECKPOINT CP-RP-2**: Code analysis complete, user agrees with recommended approach.
|
|
292
|
-
|
|
293
|
-
### Phase 4: Item Decomposition
|
|
294
|
-
|
|
295
|
-
**Goal**: Split refactoring goals into executable, well-ordered items.
|
|
296
|
-
|
|
297
|
-
Read `${SKILL_DIR}/references/planning-phases.md` for the full Phase 4-6 procedures — item decomposition patterns, per-item confirmation loop, and completeness review checklist.
|
|
298
|
-
|
|
299
|
-
**CHECKPOINT CP-RP-3**: All items decomposed with dependencies and preservation strategies.
|
|
300
|
-
|
|
301
|
-
### Phase 5: Per-Item Confirmation
|
|
302
|
-
|
|
303
|
-
**Goal**: Present each item to the user for confirmation, modification, or rejection.
|
|
304
|
-
|
|
305
|
-
See `${SKILL_DIR}/references/planning-phases.md` for the display template and confirm/modify/skip loop procedure.
|
|
306
|
-
|
|
307
|
-
**CHECKPOINT CP-RP-4**: All items confirmed by user.
|
|
308
|
-
|
|
309
|
-
### Phase 6: Headless Context Completeness Gate
|
|
310
|
-
|
|
311
|
-
**Goal**: Check every new or changed item as if the reviewer has never seen the planning conversation, including consistency, gaps, target architecture, scope boundaries, purpose-tagged target paths, behavior-preservation decisions, and completion evidence. Return `NEEDS_FIXES` for any unanswered artifact-alone question and preserve unchanged historical items.
|
|
312
|
-
|
|
313
|
-
See `${SKILL_DIR}/references/planning-phases.md` for the full 5-step review checklist (DAG validation, preservation check, gap detection, cross-module impact, headless readiness criteria) and review summary table format.
|
|
314
|
-
|
|
315
|
-
**CHECKPOINT CP-RP-5**: Headless Context Completeness Gate passed for every new or changed item, all issues resolved without relying on `user_context`.
|
|
316
|
-
|
|
317
|
-
### Phase 7: Generate & Validate
|
|
318
|
-
|
|
319
|
-
**Goal**: Produce `.prizmkit/plans/refactor-list.json` and validate it.
|
|
320
|
-
|
|
321
|
-
**IMPORTANT: Do NOT hand-write the final JSON file.** Instead:
|
|
322
|
-
1. For a new list, write the complete `.prizmkit/plans/refactor-list.draft.json`. For an existing list, follow §Bounded Existing-List Context and write only the additions-only `refactors` object. The draft is the review target, so nothing is written to the final list yet.
|
|
323
|
-
2. Once required semantic gates pass, check merge feasibility without a second draft-approval pause:
|
|
324
|
-
- New list or explicit full-list rewrite: the draft is complete and nothing exists to overwrite, so its post-review `generate` is the validator.
|
|
325
|
-
- Ordinary existing-list append:
|
|
326
|
-
```bash
|
|
327
|
-
python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py append --input .prizmkit/plans/refactor-list.draft.json --output .prizmkit/plans/refactor-list.json --dry-run
|
|
328
|
-
```
|
|
329
|
-
The dry run applies the same base, exact-ID, dependency, and complete-DAG checks the real insert will, including `append`'s preservation of root metadata and historical refactors.
|
|
330
|
-
3. If validation fails -> fix the draft and retry (max 3 attempts)
|
|
331
|
-
4. If the draft and dry run pass -> run the mandatory Local Generated-Plan Review Gate (see §Local Generated-Plan Review Gate below) on the draft; apply accepted fixes to the draft and revalidate until `PASS`
|
|
332
|
-
5. After `PASS` -> insert exactly once (`append`, or `generate` for a new list), confirm its `appended_ids`, and delete the draft under §Draft Lifecycle
|
|
333
|
-
6. Present the final written result, summary, and draft cleanup result. For later user adjustments, recreate the minimum source draft from confirmed in-memory entries or exact-ID `show`, then rerun `generate` for a new-list rewrite or `append --replace-tail` for ordinary appended entries
|
|
334
|
-
|
|
335
|
-
**CHECKPOINT CP-RP-6**: The draft batch validates and its merge dry run returns zero errors; the final list is still untouched.
|
|
336
|
-
|
|
337
|
-
**CHECKPOINT CP-RP-7**: Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only the draft batch, applied accepted fixes through the draft, revalidated, returned `PASS`, then ran exactly one insert whose `appended_ids` match the batch and removed the draft.
|
|
338
|
-
|
|
339
|
-
## Checkpoints (Mandatory Gates)
|
|
340
|
-
|
|
341
|
-
| Checkpoint | Artifact/State | Criteria | Phase |
|
|
342
|
-
|-----------|----------------|----------|-------|
|
|
343
|
-
| **CP-RP-0** | Project Context | Tech stack, test suite status, .prizmkit/prizm-docs loaded | 1 |
|
|
344
|
-
| **CP-RP-1** | Goals Collected | All refactoring goals understood, no open ambiguities | 2 |
|
|
345
|
-
| **CP-RP-2** | Code Analyzed | Analysis complete, user agrees with approach | 3 |
|
|
346
|
-
| **CP-RP-3** | Items Decomposed | All items have deps, complexity, preservation strategy | 4 |
|
|
347
|
-
| **CP-RP-4** | Items Confirmed | User confirmed/modified/skipped each item | 5 |
|
|
348
|
-
| **CP-RP-5** | Completeness OK | DAG valid, preservation strategies declared, no gaps | 6 |
|
|
349
|
-
| **CP-RP-6** | Draft Batch Ready | Additions-only or complete draft holds the whole batch with `context` IDs; merge dry run clean; final list still untouched | 7 |
|
|
350
|
-
| **CP-RP-7** | Reviewed, Then Inserted Once | Local generated-plan review loaded `${SKILL_DIR}/references/generated-plan-review.md`, reviewed only the draft batch, applied accepted fixes through the draft, revalidated, returned `PASS`, then ran exactly one insert whose `appended_ids` match the batch, and removed the draft | 7 |
|
|
351
|
-
|
|
352
|
-
## Local Generated-Plan Review Gate
|
|
353
|
-
|
|
354
|
-
Run this gate after the batch is written to the draft and passes draft validation, and before anything is written to `.prizmkit/plans/refactor-list.json`. The review target is the batch that is about to be inserted, not a file that already contains it. It applies whenever this session produced or changed a batch. For validate-only, summary-only, or draft-save flows with no batch, report that the gate is not applicable.
|
|
355
|
-
|
|
356
|
-
Read `${SKILL_DIR}/references/generated-plan-review.md` and follow it as the single source of truth. Review the draft directly, reading `.prizmkit` artifacts from disk rather than from `git status` or `git diff`, because those files may be gitignored. Use bounded `context` and explicit-ID `show` only for already-committed entries whose contract or dependency semantics a reviewed item relies on; do not load unchanged historical entries. Repeat the Headless Context Completeness Gate for every reviewed new or changed refactor. Keep the review planning-only: apply accepted findings to the draft, re-run draft validation and the merge dry run, and repeat local review until it returns `PASS`. Only then insert once and complete §Draft Lifecycle cleanup before reporting the final written result. If the insert is rejected after `PASS`, nothing landed; fix the draft, re-run validation and the dry run, and re-review only the entries you changed.
|
|
357
|
-
|
|
358
|
-
## Output Rules
|
|
359
|
-
|
|
360
|
-
`.prizmkit/plans/refactor-list.json` must satisfy:
|
|
361
|
-
- `$schema` = `dev-pipeline-refactor-list-v1`
|
|
362
|
-
- Non-empty `refactors` array
|
|
363
|
-
- Sequential IDs: `R-001`, `R-002`, ...
|
|
364
|
-
- Valid dependency DAG (no cycles)
|
|
365
|
-
- Each item has a declared `behavior_preservation` object with `strategy` field: `"test-gate"`, `"snapshot"`, or `"manual"`. Optional fields: `existing_tests` (boolean), `new_tests_needed` (string array). See `.prizmkit/dev-pipeline/templates/refactor-list-schema.json` for the full schema.
|
|
366
|
-
- `priority` must be a string: `"critical"`, `"high"`, `"medium"`, or `"low"`
|
|
367
|
-
- New items default `status: "pending"`
|
|
368
|
-
- English titles for stable slug generation
|
|
369
|
-
- `type` field must be one of: `extract`, `rename`, `restructure`, `simplify`, `decouple`, `migrate`
|
|
370
|
-
- Descriptions minimum 15 words (error). Recommended: 30/50/80 words for low/medium/high complexity (warning).
|
|
371
|
-
- `model` field is optional — omitting it means the pipeline uses $MODEL env or CLI default
|
|
372
|
-
- `scope` object with nested structure: `files` array (target file paths) and `modules` array (module names)
|
|
373
|
-
|
|
374
|
-
## Verification Defaults
|
|
375
|
-
|
|
376
|
-
Set behavior-preservation and testing expectations for each refactor item.
|
|
377
|
-
|
|
378
|
-
| Priority | Complexity | Verification expectation |
|
|
379
|
-
|----------|-----------|--------------------------|
|
|
380
|
-
| critical | high | Strong behavior-preservation evidence plus scoped tests and review gate |
|
|
381
|
-
| critical | medium/low | Focused behavior-preservation evidence plus review gate |
|
|
382
|
-
| high | high | Scoped tests for changed boundaries plus review gate |
|
|
383
|
-
| other combinations | any | Smallest meaningful behavior-preservation check |
|
|
384
|
-
|
|
385
|
-
---
|
|
386
|
-
|
|
387
|
-
## Fast Path
|
|
388
|
-
|
|
389
|
-
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.
|
|
390
|
-
|
|
391
|
-
## Browser Verification
|
|
392
|
-
|
|
393
|
-
Browser verification is supported for UI-affecting refactors as a supplement to `behavior_preservation`. Refactors must still declare `behavior_preservation.strategy`; add `browser_interaction` only when UI behavior should be visually checked after refactoring. Read `${SKILL_DIR}/references/planning-phases.md` for strategy details and UI refactoring examples.
|
|
394
|
-
|
|
395
|
-
---
|
|
396
|
-
|
|
397
|
-
## Priority and Complexity Calibration (Mandatory)
|
|
398
|
-
|
|
399
|
-
Refactor planning must not collapse into uniform `Priority: high` and `Complexity: high`. Refactoring work can be low or medium priority even when it touches several files. Do not use high/high merely because code needs cleanup, the user cares about maintainability, the target is framework code, or multiple files are involved.
|
|
400
|
-
|
|
401
|
-
### Priority Rubric
|
|
402
|
-
|
|
403
|
-
| Priority | Use When | Do NOT Use Merely Because |
|
|
404
|
-
|----------|----------|---------------------------|
|
|
405
|
-
| `critical` | Behavior-preserving restructure is required to unblock an imminent release, security/compliance fix, or safe migration with no acceptable workaround. | The refactor is large or architectural in wording. |
|
|
406
|
-
| `high` | Current structure blocks core feature delivery, creates ongoing correctness/security/data-risk, prevents supported runtime upgrades, or many downstream tasks cannot proceed. | The code is messy, multi-file, or important to the user. |
|
|
407
|
-
| `medium` | Refactor improves maintainability, testability, or dependency boundaries for planned work but does not block current operation. | Medium is the normal default for useful refactors. |
|
|
408
|
-
| `low` | Local cleanup, rename, simplification, documentation-oriented organization, or isolated code-health improvement with low behavior risk. | Small scope alone does not make it low if it blocks a high-impact outcome. |
|
|
409
|
-
|
|
410
|
-
### Complexity Rationale Rules
|
|
411
|
-
|
|
412
|
-
Assign complexity from concrete refactor scope indicators and include a short rationale:
|
|
413
|
-
- file count and expected import/update sites
|
|
414
|
-
- cross-module scope and dependency depth
|
|
415
|
-
- public API/interface or import-path change
|
|
416
|
-
- existing test coverage and behavior-preservation strategy
|
|
417
|
-
- behavior-preservation risk and snapshot/manual verification needs
|
|
418
|
-
- migration impact, rollout phases, or compatibility shims
|
|
419
|
-
|
|
420
|
-
Use `low` for 1-3 files in one module with good tests and no public API/import-path change. Use `medium` for 4-8 files or two modules with bounded public impact and clear behavior-preservation tests. Use `high` only for 9+ files, 3+ modules, public API/import-path migration, weak test coverage, manual preservation risk, or cross-module migration impact.
|
|
421
|
-
|
|
422
|
-
### Required Planning Review Summary
|
|
423
|
-
|
|
424
|
-
Before writing `.prizmkit/plans/refactor-list.json`, show a calibration table with rationale columns:
|
|
425
|
-
|
|
426
|
-
```
|
|
427
|
-
ID | Title | Priority | Priority Rationale | Complexity | Complexity Rationale
|
|
428
|
-
R-001 | Break auth/user cycle | high | Blocks feature work; core risk | high | 3 modules + public imports + weak tests
|
|
429
|
-
R-002 | Extract chart format helpers | medium | Maintainability for planned UI | medium | 5 files; bounded helper API; tests exist
|
|
430
|
-
R-003 | Rename local temp variable | low | Local readability only | low | One file; no interface or behavior change
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
Anti-pattern rule: do not assign every generated item `Priority: high` and `Complexity: high` unless each item independently satisfies the documented high-priority and high-complexity criteria and the rationale names those criteria.
|
|
434
|
-
|
|
435
|
-
## Refactoring-Specific Features
|
|
436
|
-
|
|
437
|
-
### Behavior Preservation Check
|
|
438
|
-
|
|
439
|
-
Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details. See `${SKILL_DIR}/references/planning-phases.md` for the strategy selection table and manual-strategy flagging rules.
|
|
440
|
-
|
|
441
|
-
### Dependency Ordering
|
|
442
|
-
|
|
443
|
-
Auto-detect inter-item dependencies and enforce safe ordering. Read `${SKILL_DIR}/references/planning-phases.md` for the full dependency ordering rules (safe renames -> extract/inline -> structural -> migrations).
|
|
444
|
-
|
|
445
|
-
### Complexity Assessment
|
|
446
|
-
|
|
447
|
-
Assess each item's complexity from concrete indicators: file count, cross-module scope, public API/import-path changes, dependency depth, test coverage, behavior-preservation risk, and migration impact. Read `${SKILL_DIR}/references/planning-phases.md` for the full complexity assessment criteria and scoring rules. Every confirmation/review summary must include a short complexity rationale.
|
|
448
|
-
|
|
449
|
-
## Next-Step Execution Policy (after planning)
|
|
450
|
-
|
|
451
|
-
Recommend invoking `refactor-pipeline-launcher` to configure and launch the dev-pipeline. Do NOT recommend running shell scripts directly — that is the launcher's responsibility.
|
|
452
|
-
|
|
453
|
-
## Error Recovery & Resume
|
|
454
|
-
|
|
455
|
-
When validation fails, existing planning artifacts are detected, the session is interrupted, or the user exits before producing a valid final plan, read `${SKILL_DIR}/references/error-recovery.md`. Keep recovery planning-only and resume from the artifact's actual completeness rather than restarting or guessing.
|
|
456
|
-
|
|
457
|
-
## Handoff Message Template
|
|
458
|
-
|
|
459
|
-
After the batch is inserted, report:
|
|
460
|
-
1. Output file path
|
|
461
|
-
2. Total refactor items
|
|
462
|
-
3. Dependency ordering highlights (which items must run first)
|
|
463
|
-
4. Behavior preservation strategy distribution (N items with test-gate, M with snapshot, etc.)
|
|
464
|
-
5. Local generated-plan review result: verdict, reviewed batch IDs plus reviewed root prose when applicable, and accepted fixes (or "none")
|
|
465
|
-
6. Insert result: the single writer run and the `appended_ids` it reported
|
|
466
|
-
7. Draft cleanup result: `removed`
|
|
467
|
-
8. Recommended next action: `refactor-pipeline-launcher`
|