prizmkit 1.1.191 → 1.1.193
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/adapters/antigravity/skill-adapter.js +13 -4
- 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 +28 -44
- package/bundled/dev-pipeline/assets/feature-list-example.json +0 -1
- package/bundled/dev-pipeline/assets/skill-subagent-integration.md +6 -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 +48 -78
- package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +127 -67
- package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +158 -462
- package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +102 -50
- package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -25
- package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
- package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +47 -21
- package/bundled/dev-pipeline/prizmkit_runtime/processes.py +217 -156
- package/bundled/dev-pipeline/prizmkit_runtime/reset.py +39 -27
- package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +34 -174
- package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
- package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +133 -110
- package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
- package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -95
- 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 +540 -262
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +175 -135
- package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
- package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +214 -133
- package/bundled/dev-pipeline/prizmkit_runtime/status.py +1 -3
- package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2783 -0
- package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -102
- package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
- package/bundled/dev-pipeline/scripts/check-session-status.py +56 -20
- package/bundled/dev-pipeline/scripts/continuation.py +8 -7
- package/bundled/dev-pipeline/scripts/detect-stuck.py +47 -33
- package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +13 -16
- package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +20 -10
- package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
- package/bundled/dev-pipeline/scripts/init-change-artifact.py +25 -4
- package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
- package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2616
- package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
- package/bundled/dev-pipeline/scripts/prompt_framework.py +85 -20
- 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 +254 -65
- package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
- package/bundled/dev-pipeline/scripts/utils.py +5 -12
- package/bundled/dev-pipeline/templates/bootstrap-tier3.md +5 -5
- package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
- package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +7 -7
- 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/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 +24 -127
- package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
- 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/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/scaffold.js +28 -7
- 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/conftest.py +0 -29
- package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +0 -208
- package/bundled/dev-pipeline/tests/test_auto_skip.py +0 -1871
- package/bundled/dev-pipeline/tests/test_checkpoint_state.py +0 -1314
- package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +0 -1712
- package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +0 -627
- package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
- package/bundled/dev-pipeline/tests/test_python_runner_parity.py +0 -5641
- package/bundled/dev-pipeline/tests/test_recovery_workflow.py +0 -322
- package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -252
- package/bundled/dev-pipeline/tests/test_reset_modes.py +0 -1208
- package/bundled/dev-pipeline/tests/test_reset_preserve.py +0 -957
- package/bundled/dev-pipeline/tests/test_runtime_commit.py +0 -1113
- package/bundled/dev-pipeline/tests/test_runtime_helper.py +0 -303
- package/bundled/dev-pipeline/tests/test_unified_cli.py +0 -5504
- package/bundled/dev-pipeline/tests/test_utils.py +0 -170
- 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,107 +0,0 @@
|
|
|
1
|
-
# Generated Plan Review — Refactor Planner
|
|
2
|
-
|
|
3
|
-
Use this local review loop on the batch that is about to be inserted into `.prizmkit/plans/refactor-list.json`. This is a planner-output review, not an implementation/code-diff review, and it runs before the insert so the verdict decides whether the batch lands.
|
|
4
|
-
|
|
5
|
-
## Trigger
|
|
6
|
-
|
|
7
|
-
Run only when the current `refactor-planner` session produced a draft batch of new or changed refactors. For validate-only, summary-only, or draft-save flows with no new batch, report: `Local generated-plan review: not applicable — no new planning content written.`
|
|
8
|
-
|
|
9
|
-
The draft is the whole review surface. Nothing is written to the final list while this loop runs: the single insert happens only after a `PASS`, so the verdict decides whether the batch lands and no final list ever holds reviewed-looking entries that were never reviewed.
|
|
10
|
-
|
|
11
|
-
## Direct Artifact Reads
|
|
12
|
-
|
|
13
|
-
Planning artifacts may be gitignored, untracked, or absent from staged and unstaged diffs. Read the actual files through bounded, source-first access:
|
|
14
|
-
|
|
15
|
-
- Review target: `.prizmkit/plans/refactor-list.draft.json` — the additions-only or complete batch, read in full; this is the only planning content under review
|
|
16
|
-
- Final list: `.prizmkit/plans/refactor-list.json` — run the `context` command for root prose and recent IDs; do not load the complete historical list into AI context, and do not expect this session's batch to appear in it yet
|
|
17
|
-
- Pre-session final list snapshot if captured in memory before edits — retain only bounded root context, prior task count/next ID, and the five recent `{id, description}` pairs, not full history
|
|
18
|
-
- In-memory draft object if the session has not written a draft file yet
|
|
19
|
-
- Already-committed entries a reviewed item relies on — load each referenced ID with `python3 ${SKILL_DIR}/scripts/validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-NNN`
|
|
20
|
-
|
|
21
|
-
Do not rely on `git status`, `git diff`, or `git diff --cached` to decide whether planner output exists or changed. If the final list already contains this session's batch, the insert ran before the verdict — report that instead of reviewing an already-landed batch. Do not invoke `/prizmkit-code-review` for this planner-output gate; `/prizmkit-code-review` remains the implementation/code-diff review gate after `/prizmkit-implement`.
|
|
22
|
-
|
|
23
|
-
## Review Scope
|
|
24
|
-
|
|
25
|
-
1. Treat the draft batch as the change set. Its `R-*` IDs are the sequential `context` IDs the writer demands at insert time, so the IDs reviewed are the IDs that land; do not compare complete pre/post historical arrays in AI context.
|
|
26
|
-
2. Root project prose is reviewable content, not generator metadata. Read it through `context`; review new or changed `project_description` and `global_context` even when no refactor item changed. Ignore root generator metadata and formatting-only differences such as `$schema`, `created_at`, and `created_by`.
|
|
27
|
-
3. Treat refactors as changed only when item fields changed; load and review newly added refactor IDs and explicitly changed refactor IDs through `show`.
|
|
28
|
-
4. Preserve unchanged historical refactors. Do not load unchanged entries merely to establish review completeness. Use the full-list validator for dependency/DAG truth; use `show` for an old dependency or behavior-preservation interaction only when a specific reviewed refactor requires semantic inspection.
|
|
29
|
-
5. If no snapshot exists during initial generation, review all entries in that session's complete draft. Absence of a snapshot never authorizes loading unrelated history during append flow.
|
|
30
|
-
|
|
31
|
-
## Review Checklist
|
|
32
|
-
|
|
33
|
-
For every reviewed refactor entry, check:
|
|
34
|
-
|
|
35
|
-
- Intent fidelity: confirmed structural outcome, behavior invariants, scope, non-goals, and constraints preserve user intent rather than an AI-selected architecture
|
|
36
|
-
- Evidence status honesty: current-state facts, evidence-backed inferences, recommendations, assumptions, and unknowns remain distinct; proposed target architecture is not presented as confirmed until selected
|
|
37
|
-
- Minimum-sufficient scope: every operation maps to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk; unrelated cleanup and speculative redesign are absent
|
|
38
|
-
- Schema compatibility with `dev-pipeline-refactor-list-v1` and `.prizmkit/dev-pipeline/templates/refactor-list-schema.json`
|
|
39
|
-
- Dependency/DAG soundness, including safe behavior-preserving order
|
|
40
|
-
- Description completeness: objective, current state, desired target architecture, selected decisions, scope boundaries, constraints, non-goals, relevant integrations and consumers, edge cases, behavior-preservation decisions, completion evidence, and headless execution readiness
|
|
41
|
-
- Artifact-wide readability: every generated natural-language value across all AI-visible fields and sections—including `project_description`, `global_context`, scope explanations, rationales, behavior-preservation/evidence text, `user_context`, comments, and parentheticals—is a standalone domain statement without dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance
|
|
42
|
-
- Acceptance criteria specificity and measurable behavior-preservation verification
|
|
43
|
-
- `behavior_preservation` strategy quality and consistency with target scope and existing tests
|
|
44
|
-
- User-provided detail preservation at matching detail after conversational normalization
|
|
45
|
-
- `user_context` is supplementary evidence only: it does not expand, replace, or contradict the refactor contract; if `user_context` were removed, execution and verification remain unambiguous
|
|
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
|
-
- 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
|
-
- 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
|
-
- Insert feasibility: every `dependencies` entry on a committed ID exists in the final list, the batch uses the consecutive IDs `context` reported, and the merge dry run returns `"valid": true`. Draft-only validation cannot see the merged graph, so a `PASS` without this check is a verdict the writer may reject.
|
|
52
|
-
- Size: there is no word-count upper limit and no acceptance-criteria count upper limit
|
|
53
|
-
|
|
54
|
-
## Headless Context Completeness Gate
|
|
55
|
-
|
|
56
|
-
Repeat the pre-generation simulation for every reviewed new or changed refactor as if the reviewer has never seen the planning conversation. First scan all AI-visible fields and sections; machine metadata is exempt, but every generated natural-language value must be session-independent. From the artifact alone, answer:
|
|
57
|
-
|
|
58
|
-
1. What exact confirmed structural problem or outcome is this task responsible for, and how does it preserve the intent baseline?
|
|
59
|
-
2. What current architecture exists according to evidence, which target statements are confirmed versus recommended/assumed, and what target architecture must replace it?
|
|
60
|
-
3. Which approach was selected, expressed by meaning rather than an option label?
|
|
61
|
-
4. What scope boundaries, constraints, and non-goals must be preserved?
|
|
62
|
-
5. Why is each reference material and target path relevant?
|
|
63
|
-
6. How can completion and behavior preservation be verified?
|
|
64
|
-
7. Does any phrase require an unseen earlier question, recommendation, or option list?
|
|
65
|
-
8. Do quoted source materials agree with the final task decision?
|
|
66
|
-
9. Does every operation have a confirmed structural goal, behavior invariant, existing contract, or evidenced risk, with no unrelated cleanup or speculative redesign?
|
|
67
|
-
|
|
68
|
-
Return `NEEDS_FIXES` if any answer is missing, ambiguous, available only in `user_context`, or dependent on shorthand such as `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`. Parenthetical notes are part of the artifact and must pass the same fresh-session test. Do not emit transcript annotations such as `(original response: "...")`; raw shorthand is not independently intelligible and materially useful. Preserve substantive rationale in the durable refactor contract. Treat `所有问题都按你的推荐处理`, `全部按照推荐`, `use all recommendations`, and equivalent blanket recommendation approval as conversational authorization: write the concrete accepted decisions, omit the raw approval, and never repeat it once per accepted recommendation. Do not retain non-code planning-source paths such as `.agents/brainstorm/<note>.md`; copy or normalize the task-relevant content into the contract, which must not depend on that source file still existing. Ask the user for clarification when there is not one provable antecedent.
|
|
69
|
-
|
|
70
|
-
Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures. Apply this stricter gate prospectively to new or changed entries and preserve unchanged historical refactors.
|
|
71
|
-
|
|
72
|
-
### Good and Bad Review Examples
|
|
73
|
-
|
|
74
|
-
- Bad: `go with your recommendation` as target architecture or as `(original response: "go with your recommendation")`; Good: `Selected decision: reverse the auth/user dependency through a shared identity interface and retain existing public imports`.
|
|
75
|
-
- Bad: repeating `(original response: "全部按照推荐")`; Good: omit the blanket approval after writing each concrete accepted decision.
|
|
76
|
-
- Bad: bare `src/auth/`; Good: `src/auth/ — inspect public exports, dependency direction, and compatibility call sites before restructuring`.
|
|
77
|
-
- Bad: an entire RFC pasted into evidence or `.agents/brainstorm/refactor.md` retained as a requirement; Good: inline task-relevant excerpts and all confirmed target decisions, then omit the transient planning path.
|
|
78
|
-
|
|
79
|
-
## Fix Loop
|
|
80
|
-
|
|
81
|
-
1. Present findings with IDs, severity, evidence, and suggested draft/source changes.
|
|
82
|
-
2. Accept only findings that improve planner correctness, completeness, or downstream behavior-preserving execution readiness.
|
|
83
|
-
3. Apply accepted fixes to `.prizmkit/plans/refactor-list.draft.json` or the in-memory draft object first.
|
|
84
|
-
4. Re-check the fixed draft without writing:
|
|
85
|
-
|
|
86
|
-
```bash
|
|
87
|
-
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
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
The dry run enforces the same base, exact-ID, dependency, and complete-DAG checks as the real insert, so keep it green instead of discovering a merge conflict after `PASS`. A new list or explicit full-list rewrite has no merged graph to check and nothing to overwrite, so its single post-`PASS` `generate` is the validator; if it rejects the draft, fix and retry, because no file was written.
|
|
91
|
-
|
|
92
|
-
5. Never hand-patch `.prizmkit/plans/refactor-list.json` as the source of truth and do not add a user approval round for the mechanical rewrite.
|
|
93
|
-
6. Repeat the local review and Headless Context Completeness Gate only for entries changed by accepted fixes.
|
|
94
|
-
7. Do not report `PASS` until every required fresh-session answer is available and the draft validation plus merge dry run pass.
|
|
95
|
-
8. After `PASS`, insert the batch exactly once (`append`, or `generate` for a new list), confirm the writer's `appended_ids`, then delete `.prizmkit/plans/refactor-list.draft.json`. Retain a draft only under the conditions in `${SKILL_DIR}/references/error-recovery.md`; report the retained path and reason.
|
|
96
|
-
|
|
97
|
-
## Report Format
|
|
98
|
-
|
|
99
|
-
Report in the final handoff summary:
|
|
100
|
-
|
|
101
|
-
- `Local generated-plan review: PASS` or `NEEDS_FIXES`
|
|
102
|
-
- Reviewed batch IDs and reviewed root prose (`project_description` / `global_context`) when applicable
|
|
103
|
-
- Merge dry-run result
|
|
104
|
-
- Accepted fixes, or `none`
|
|
105
|
-
- Insert result: the single writer run and the `appended_ids` it reported
|
|
106
|
-
- Draft cleanup result: `removed`, or retained path and recovery reason
|
|
107
|
-
- Note when review was not applicable because no new planning content was written
|
|
@@ -1,172 +0,0 @@
|
|
|
1
|
-
# Planning Phases — Refactor Planner
|
|
2
|
-
|
|
3
|
-
Detailed procedures for Phases 4-6 of the refactor-planner interactive workflow, plus refactoring-specific assessment rules and browser verification guidance.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Phase 4: Item Decomposition Procedure
|
|
8
|
-
|
|
9
|
-
Read `${SKILL_DIR}/assets/planning-guide.md` for decomposition patterns and dependency ordering rules.
|
|
10
|
-
|
|
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. 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
|
-
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
|
-
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
|
-
4. Assign priority from concrete impact (blocked delivery, correctness/security/data risk, maintainability value, or local cleanup), not from size or user urgency alone
|
|
16
|
-
5. Assign behavior preservation strategy per item (read `${SKILL_DIR}/references/behavior-preservation.md`)
|
|
17
|
-
|
|
18
|
-
---
|
|
19
|
-
|
|
20
|
-
## Phase 5: Per-Item Confirmation Loop
|
|
21
|
-
|
|
22
|
-
Present items in reviewable groups. Use `AskUserQuestion` for each consequential scope, target-architecture, public-contract, migration, or behavior-preservation decision; independent low-risk items may share one confirmation batch when their meanings remain clear:
|
|
23
|
-
|
|
24
|
-
```text
|
|
25
|
-
Refactor Item R-001:
|
|
26
|
-
Title: [title]
|
|
27
|
-
Type: [extract/rename/restructure/simplify/decouple/migrate]
|
|
28
|
-
Scope: [files list]
|
|
29
|
-
Priority: [critical/high/medium/low]
|
|
30
|
-
Priority Rationale: [short concrete impact reason]
|
|
31
|
-
Complexity: [low/medium/high]
|
|
32
|
-
Complexity Rationale: [short scope/risk reason]
|
|
33
|
-
Behavior Preservation: [test-gate/snapshot/manual]
|
|
34
|
-
Acceptance Criteria:
|
|
35
|
-
- [criterion 1]
|
|
36
|
-
- [criterion 2]
|
|
37
|
-
Dependencies: [none / R-002, R-003]
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
Offer `Accept`, `Modify`, and `Skip` as selectable options. Re-display modified consequential items before acceptance. Do not ask the user to approve unconstrained implementation mechanics that preserve all confirmed boundaries and remain locally reversible.
|
|
41
|
-
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## Phase 6: Completeness Review Checklist
|
|
45
|
-
|
|
46
|
-
1. **Dependency ordering check**: Verify items form a valid DAG (no cycles). Follow verified producer/consumer dependencies; otherwise prefer the risk-reducing order safe renames -> extract/inline -> structural changes -> migrations.
|
|
47
|
-
2. **Behavior preservation check**: Every item must have a declared preservation strategy. Flag any item with `manual` strategy and no test coverage.
|
|
48
|
-
3. **Gap detection**: Are there intermediate steps needed between items? Does item A's output match item B's input assumption?
|
|
49
|
-
4. **Cross-module impact**: Do any items affect modules outside the declared scope?
|
|
50
|
-
5. **Intent and design necessity**: Does every item map to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk? Remove unrelated cleanup and speculative redesign.
|
|
51
|
-
6. **Evidence status**: Are current-state observations, inferred architecture, recommendations, assumptions, and unknowns labeled distinctly? No AI-proposed architecture may appear as confirmed user intent without confirmation.
|
|
52
|
-
7. **Headless Context Completeness Gate**: Review every new or changed item as if the reviewer has never seen the planning conversation. Preserve unchanged historical items. Scan all AI-visible fields and sections first: every generated natural-language value in `project_description`, `global_context`, item fields, scope explanations, behavior-preservation/evidence text, `user_context`, comments, and parentheticals must be session-independent, with no dialogue-role labels, question IDs, answer tokens, planning-option recommendation markers, or planning provenance. Review changed root prose even when no refactor item changed. Then assess `description` plus `acceptance_criteria` without `user_context` and answer from the artifact alone:
|
|
53
|
-
1. What exact confirmed structural problem or outcome is this task responsible for, and how does it preserve the intent baseline?
|
|
54
|
-
2. What current architecture exists according to evidence, which target statements are confirmed versus recommended/assumed, and what target architecture must replace it?
|
|
55
|
-
3. Which approach was selected, expressed by meaning rather than an option label?
|
|
56
|
-
4. What scope boundaries, constraints, and non-goals must be preserved?
|
|
57
|
-
5. Why is each reference material and target path relevant, and what should be inspected?
|
|
58
|
-
6. Which integrations, consumers, import paths, and edge cases are affected?
|
|
59
|
-
7. Which behavior-preservation decisions and completion evidence prove equivalence?
|
|
60
|
-
8. Does any phrase require an unseen earlier question, recommendation, or option list?
|
|
61
|
-
9. Do quoted source materials agree with the final task decision?
|
|
62
|
-
10. Does every operation map to a confirmed structural goal, behavior invariant, existing contract, or evidenced risk, with no unrelated cleanup or speculative redesign?
|
|
63
|
-
|
|
64
|
-
Return `NEEDS_FIXES` whenever any answer is missing, ambiguous, or available only in `user_context`. Parenthetical notes must pass the same gate. Do not emit transcript annotations such as `(original response: "...")`; preserve substantive rationale, but omit bare selection tokens and `全部按照推荐` or equivalent blanket recommendation approval after normalization. Ask the user for clarification when a relative statement has more than one plausible antecedent; never guess.
|
|
65
|
-
|
|
66
|
-
- **Scope clarity**: List all affected files and explain each file or coherent group as purpose-tagged target paths.
|
|
67
|
-
- **Target architecture**: State concrete module ownership, interfaces, dependency direction, compatibility boundaries, and desired end state.
|
|
68
|
-
- **Behavior preservation**: State what tests, snapshots, or reproducible checks run and which observable behavior must remain equivalent.
|
|
69
|
-
- **Dependency context**: State which exact earlier refactor output this item consumes.
|
|
70
|
-
- **Good**: `Extract validateEmail, validatePhone, and validateUrl from src/utils/helpers.ts into src/utils/validation.ts; update all 12 import sites; preserve signatures and error semantics. src/utils/helpers.ts — inspect current exports and callers before extraction.`
|
|
71
|
-
- **Bad**: `Clean up the utils module`, `方案B`, `按推荐走`, `use option A`, `same as above`, or `go with your recommendation`.
|
|
72
|
-
- **Bad normalization**: append `(original response: "方案B")` to a complete architecture decision; the annotation is not independently intelligible and materially useful.
|
|
73
|
-
- **Good normalization**: `Selected decision: introduce an auth-owned validation module while retaining existing public imports through compatibility re-exports`.
|
|
74
|
-
- **Bad material handling**: embed an entire architecture RFC while saying `apply this`, or retain `.agents/brainstorm/refactor.md` as a final requirement source.
|
|
75
|
-
- Do not retain non-code planning-source paths in the final contract.
|
|
76
|
-
- **Good material handling**: copy or normalize the task-relevant content and exact excerpts into the contract; retain only purpose-tagged stable execution targets. The item must not depend on that source file still existing.
|
|
77
|
-
- Exclude `所有问题都按你的推荐处理`, `全部按照推荐`, and equivalent conversational authorization when it does not constrain implementation; never repeat it once per accepted recommendation.
|
|
78
|
-
- `user_context` is supplementary evidence only. If `user_context` were removed, execution and verification must remain unambiguous at matching detail.
|
|
79
|
-
- Do not add new JSON fields, context objects, schema versions, or pipeline runtime structures.
|
|
80
|
-
|
|
81
|
-
### Review Summary Table Format
|
|
82
|
-
|
|
83
|
-
Present review summary:
|
|
84
|
-
|
|
85
|
-
```
|
|
86
|
-
Item | Priority | Priority Rationale | Complexity | Complexity Rationale | Deps Valid | Preservation | Gaps | Status
|
|
87
|
-
R-001 | high | Blocks core feature work | high | 3 modules + public imports | OK | test-gate | - | Ready
|
|
88
|
-
R-002 | medium | Planned maintainability | medium | 5 files + tests exist | OK | test-gate | - | Ready
|
|
89
|
-
R-003 | low | Local readability only | low | One file, no API change | OK | manual | No test coverage| Needs attention
|
|
90
|
-
R-004 | medium | Reduces bounded coupling | medium | 2 modules + snapshot check | OK | snapshot | - | Ready
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
If issues are found, discuss with the user, apply fixes to the draft/source item, and rerun the Headless Context Completeness Gate until every new or changed item returns `PASS` before proceeding.
|
|
94
|
-
|
|
95
|
-
---
|
|
96
|
-
|
|
97
|
-
## Behavior Preservation Check
|
|
98
|
-
|
|
99
|
-
Every item MUST declare a behavior preservation strategy. Read `${SKILL_DIR}/references/behavior-preservation.md` for strategy details.
|
|
100
|
-
|
|
101
|
-
| Strategy | When to Use |
|
|
102
|
-
|----------|-------------|
|
|
103
|
-
| `test-gate` | Reliable tests cover the preserved contract; record the relevant evidence and the required downstream pass condition. |
|
|
104
|
-
| `snapshot` | Deterministic output or state can be compared; record representative inputs, normalization, and required equivalence. |
|
|
105
|
-
| `manual` | Human judgment is unavoidable; record a reproducible checklist and flag the higher verification risk. |
|
|
106
|
-
|
|
107
|
-
Flag items using `manual` strategy prominently — they carry the highest risk of behavior regression.
|
|
108
|
-
|
|
109
|
-
---
|
|
110
|
-
|
|
111
|
-
## Dependency Ordering
|
|
112
|
-
|
|
113
|
-
Auto-detect producer/consumer dependencies and enforce the resulting safe order. When no evidence requires another sequence, use this risk-reducing heuristic:
|
|
114
|
-
1. **Safe renames** first (lowest risk, no structural change)
|
|
115
|
-
2. **Extract/inline** operations (moderate risk, changes module boundaries)
|
|
116
|
-
3. **Structural changes** (higher risk, reorganizes architecture)
|
|
117
|
-
4. **Migrations** last (highest risk, changes patterns/paradigms)
|
|
118
|
-
|
|
119
|
-
Do not reorder items against verified dependencies merely to match the heuristic.
|
|
120
|
-
|
|
121
|
-
---
|
|
122
|
-
|
|
123
|
-
## Complexity Assessment
|
|
124
|
-
|
|
125
|
-
Complexity is a behavior-preserving execution risk estimate, not a measure of how much the user wants the refactor. Do not default to high because a refactor spans multiple files, targets framework code, or improves maintainability.
|
|
126
|
-
|
|
127
|
-
Assess each item's complexity based on:
|
|
128
|
-
- **File count**: 1-3 files = low, 4-8 files = medium, 9+ files = high
|
|
129
|
-
- **Cross-module scope**: same module = low, 2 modules = medium, 3+ modules = high
|
|
130
|
-
- **Public API/import-path impact**: no public change = low, bounded internal interface = medium, public API/import migration = high
|
|
131
|
-
- **Dependency depth**: 0-2 import/update sites = low, 3-5 = medium, 6+ = high
|
|
132
|
-
- **Test coverage**: strong existing tests can keep complexity lower; weak/missing tests increase complexity
|
|
133
|
-
- **Behavior-preservation risk**: test-gate with clear assertions = lower, snapshot/manual verification = higher
|
|
134
|
-
- **Migration impact**: no rollout = low, compatibility shim = medium, cross-module migration or phased rollout = high
|
|
135
|
-
|
|
136
|
-
Take the highest well-supported individual assessment as the item's complexity, then record the rationale in the confirmation table.
|
|
137
|
-
|
|
138
|
-
### Mixed Calibration Examples
|
|
139
|
-
|
|
140
|
-
| Refactor | Priority | Complexity | Rationale |
|
|
141
|
-
|----------|----------|------------|-----------|
|
|
142
|
-
| Break circular dependency blocking auth feature work | high | high | Blocks core delivery; 3 modules, public imports, and weak tests. |
|
|
143
|
-
| Extract chart formatting helpers from dashboard files | medium | medium | Improves planned maintainability; 5 files with bounded helper API and existing tests. |
|
|
144
|
-
| Rename local variable in parser for readability | low | low | Local cleanup only; one file, no interface or behavior change. |
|
|
145
|
-
|
|
146
|
-
Anti-pattern: do not generate an all-high refactor list unless every item independently satisfies documented high-priority and high-complexity criteria.
|
|
147
|
-
|
|
148
|
-
---
|
|
149
|
-
|
|
150
|
-
## Browser Verification
|
|
151
|
-
|
|
152
|
-
Browser verification is supported for UI-affecting refactors, but it is supplemental. Every refactor still uses `behavior_preservation.strategy` as the primary preservation contract:
|
|
153
|
-
|
|
154
|
-
- `strategy: test-gate` — Record the relevant existing tests and the required downstream pass condition.
|
|
155
|
-
- `strategy: snapshot` — Record the representative inputs, observable outputs, and allowed normalization for downstream comparison.
|
|
156
|
-
- `strategy: manual` — Record a reproducible human-verification checklist and the reason automated evidence is insufficient.
|
|
157
|
-
|
|
158
|
-
For refactors that modify UI code, add `browser_interaction.verify_steps` when visual or browser-flow verification is useful. Also keep behavior-preservation acceptance criteria explicit:
|
|
159
|
-
|
|
160
|
-
Example:
|
|
161
|
-
```
|
|
162
|
-
Refactor Title: Extract UserProfile component from AccountSettings
|
|
163
|
-
Type: extract
|
|
164
|
-
Strategy: snapshot
|
|
165
|
-
Acceptance Criteria:
|
|
166
|
-
1. UserProfile component renders identically to inline version (compare snapshots)
|
|
167
|
-
2. All props are correctly forwarded (unit tests pass)
|
|
168
|
-
3. No visual regression (screenshot comparison)
|
|
169
|
-
4. Component is reusable in other views
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
The generated plan supplies this evidence contract to the autonomous refactor session; this planner does not execute the verification.
|
|
@@ -1,230 +0,0 @@
|
|
|
1
|
-
# Refactor Scoping Guide
|
|
2
|
-
|
|
3
|
-
This guide helps assess refactoring scope, determine the appropriate approach, and identify risks before decomposing into executable items.
|
|
4
|
-
|
|
5
|
-
Treat numeric thresholds and named patterns in this guide as evidence prompts, not user-intent overrides. Base the final scope, complexity, and decomposition on verified files, consumers, contracts, tests, and the confirmed structural goal. Label estimates as recommendations or assumptions until evidence supports them.
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## 1. Scope Classification
|
|
10
|
-
|
|
11
|
-
Classify the observed refactoring effort into the closest of three scope categories. Classification recommends planning depth; it does not expand the user's goal or make a larger target architecture mandatory.
|
|
12
|
-
|
|
13
|
-
### Incremental Refactoring
|
|
14
|
-
|
|
15
|
-
**Definition**: Gradual, low-risk improvements applied piece by piece. Each step is independently deployable.
|
|
16
|
-
|
|
17
|
-
**Characteristics**:
|
|
18
|
-
- Targets a specific area without restructuring the whole module
|
|
19
|
-
- Each item can be merged independently
|
|
20
|
-
- Low coordination overhead between items
|
|
21
|
-
- Suitable for ongoing tech debt reduction
|
|
22
|
-
|
|
23
|
-
**When to use**:
|
|
24
|
-
- Code smell is localized (one file, one function, one class)
|
|
25
|
-
- Team wants continuous improvement without large PRs
|
|
26
|
-
- Risk tolerance is low
|
|
27
|
-
- No architectural changes needed
|
|
28
|
-
|
|
29
|
-
**Planning depth**: Lightweight. Phase 3 (Code Analysis) can be abbreviated. Fast path may apply.
|
|
30
|
-
|
|
31
|
-
### Full Refactoring
|
|
32
|
-
|
|
33
|
-
**Definition**: Comprehensive restructuring of an entire module, subsystem, or architectural layer.
|
|
34
|
-
|
|
35
|
-
**Characteristics**:
|
|
36
|
-
- Touches many files across the target area
|
|
37
|
-
- Items have significant interdependencies
|
|
38
|
-
- Requires careful ordering and coordination
|
|
39
|
-
- Higher risk, bigger payoff
|
|
40
|
-
- May need a feature branch or phased rollout
|
|
41
|
-
|
|
42
|
-
**When to use**:
|
|
43
|
-
- Module has accumulated significant tech debt
|
|
44
|
-
- Current structure actively impedes feature development
|
|
45
|
-
- Multiple code smells are interconnected
|
|
46
|
-
- Architecture needs fundamental restructuring
|
|
47
|
-
|
|
48
|
-
**Planning depth**: Full workflow required. All 7 phases mandatory. No fast path.
|
|
49
|
-
|
|
50
|
-
### Targeted Refactoring
|
|
51
|
-
|
|
52
|
-
**Definition**: Focused on a specific concern, pattern, or dependency — not the entire module.
|
|
53
|
-
|
|
54
|
-
**Characteristics**:
|
|
55
|
-
- Clear, narrow objective (e.g., "extract payment logic", "break circular dependency")
|
|
56
|
-
- May touch multiple files but only for the specific concern
|
|
57
|
-
- Moderate risk
|
|
58
|
-
- Well-defined "done" state
|
|
59
|
-
|
|
60
|
-
**When to use**:
|
|
61
|
-
- Specific pain point identified (circular dependency, god class, leaky abstraction)
|
|
62
|
-
- New feature requires cleaner structure in one area
|
|
63
|
-
- Code review identified a specific structural issue
|
|
64
|
-
|
|
65
|
-
**Planning depth**: Standard workflow. Phase 3 focuses on the specific concern.
|
|
66
|
-
|
|
67
|
-
---
|
|
68
|
-
|
|
69
|
-
## 2. File Impact Analysis
|
|
70
|
-
|
|
71
|
-
Before decomposing, assess the blast radius of the proposed refactoring.
|
|
72
|
-
|
|
73
|
-
### Impact Assessment Steps
|
|
74
|
-
|
|
75
|
-
1. **Identify primary targets**: Files/modules directly being refactored
|
|
76
|
-
2. **Trace imports/dependencies**: What files import from the targets?
|
|
77
|
-
3. **Trace test files**: What test files exercise the targets?
|
|
78
|
-
4. **Trace configuration**: Do any config files reference the targets (routes, DI containers, etc.)?
|
|
79
|
-
5. **Count total affected files**: Primary + importing + testing + config
|
|
80
|
-
|
|
81
|
-
### Impact Categories
|
|
82
|
-
|
|
83
|
-
Use file counts as an initial heuristic, then adjust from verified public contracts, dependency direction, behavior risk, and test coverage. A high count of mechanical import updates can be lower risk than one safety-critical public contract.
|
|
84
|
-
|
|
85
|
-
| Affected Files | Impact Level | Planning Implication |
|
|
86
|
-
|---------------|-------------|---------------------|
|
|
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
|
-
|
|
92
|
-
### Dependency Graph Analysis
|
|
93
|
-
|
|
94
|
-
For each target file, map:
|
|
95
|
-
- **Incoming dependencies**: Who imports/uses this file? (blast radius)
|
|
96
|
-
- **Outgoing dependencies**: What does this file import? (coupling assessment)
|
|
97
|
-
- **Circular dependencies**: Does this file participate in any cycles? (critical risk)
|
|
98
|
-
|
|
99
|
-
Tools to assess:
|
|
100
|
-
```bash
|
|
101
|
-
# Find all importers of a module (JS/TS)
|
|
102
|
-
grep -r "from.*['\"].*target-module" --include="*.js" --include="*.ts" -l
|
|
103
|
-
|
|
104
|
-
# Find all importers of a module (Python)
|
|
105
|
-
grep -r "from.*target_module\|import.*target_module" --include="*.py" -l
|
|
106
|
-
|
|
107
|
-
# Count total affected files
|
|
108
|
-
# Primary targets + importers + their test files
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
---
|
|
112
|
-
|
|
113
|
-
## 3. Cross-Module Dependency Assessment
|
|
114
|
-
|
|
115
|
-
Cross-module refactoring carries higher risk because changes ripple through module boundaries.
|
|
116
|
-
|
|
117
|
-
### Assessment Checklist
|
|
118
|
-
|
|
119
|
-
| Question | If Yes |
|
|
120
|
-
|----------|--------|
|
|
121
|
-
| Does the refactoring change any module's public API? | All consumers must be updated. Document API changes explicitly. |
|
|
122
|
-
| Does it change import paths? | All importers must be updated. Consider re-exports for backward compatibility. |
|
|
123
|
-
| Does it move shared types/interfaces? | All type consumers must be updated. May need temporary type aliases. |
|
|
124
|
-
| Does it change event/message contracts? | All subscribers/handlers must be updated. Version the contract if possible. |
|
|
125
|
-
| Does it affect database schema? | Migration required. This may be beyond refactoring scope. |
|
|
126
|
-
| Does it change configuration format? | Config consumers must be updated. Consider backward-compatible format. |
|
|
127
|
-
|
|
128
|
-
### Cross-Module Risk Mitigation
|
|
129
|
-
|
|
130
|
-
1. **Re-export pattern**: When moving a module, leave a re-export at the old path during transition
|
|
131
|
-
2. **Adapter pattern**: When changing an interface, create an adapter that bridges old and new
|
|
132
|
-
3. **Feature flag**: For risky cross-module changes, implement behind a flag
|
|
133
|
-
4. **Phased rollout**: Update consumers module by module, not all at once
|
|
134
|
-
|
|
135
|
-
---
|
|
136
|
-
|
|
137
|
-
## 4. Risk Assessment Framework
|
|
138
|
-
|
|
139
|
-
Assess risk for each refactoring item and for the overall plan.
|
|
140
|
-
|
|
141
|
-
### Per-Item Risk Factors
|
|
142
|
-
|
|
143
|
-
Use only measurements supported by repository evidence. If coverage, code age, complexity, or dependency counts are unknown, mark them unknown rather than selecting a risk band from intuition.
|
|
144
|
-
|
|
145
|
-
| Factor | Low Risk | Medium Risk | High Risk |
|
|
146
|
-
|--------|----------|-------------|-----------|
|
|
147
|
-
| Test coverage | >80% on target | 40-80% | <40% |
|
|
148
|
-
| Dependency count | 0-2 dependents | 3-5 dependents | 6+ dependents |
|
|
149
|
-
| Code age | Recently written/modified | 6-12 months old | 1+ year untouched |
|
|
150
|
-
| Documentation | Well-documented | Partially documented | No documentation |
|
|
151
|
-
| Complexity (cyclomatic) | <10 | 10-20 | >20 |
|
|
152
|
-
| Cross-module impact | None | 1 other module | 2+ other modules |
|
|
153
|
-
|
|
154
|
-
### Overall Plan Risk
|
|
155
|
-
|
|
156
|
-
Aggregate item risks to assess the plan:
|
|
157
|
-
- **Low risk plan**: All items are low risk, or mostly low with 1-2 medium
|
|
158
|
-
- **Medium risk plan**: Mix of low and medium, or 1-2 high risk items
|
|
159
|
-
- **High risk plan**: Multiple high risk items, or cross-module migration
|
|
160
|
-
|
|
161
|
-
### Risk Mitigation Strategies
|
|
162
|
-
|
|
163
|
-
| Risk Level | Strategy |
|
|
164
|
-
|-----------|----------|
|
|
165
|
-
| Low | Standard test-gate, proceed normally |
|
|
166
|
-
| Medium | Ensure snapshot comparison, add extra acceptance criteria |
|
|
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
|
-
|
|
170
|
-
---
|
|
171
|
-
|
|
172
|
-
## 5. When to Split Large Refactors
|
|
173
|
-
|
|
174
|
-
### Splitting Heuristics
|
|
175
|
-
|
|
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
|
-
|
|
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
|
-
|
|
184
|
-
### How to Split
|
|
185
|
-
|
|
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.
|
|
193
|
-
|
|
194
|
-
### Merging Split Plans
|
|
195
|
-
|
|
196
|
-
When executing split plans sequentially:
|
|
197
|
-
- Run the first plan fully (including validation)
|
|
198
|
-
- Verify all tests pass after the first plan
|
|
199
|
-
- Then start planning the second phase (the codebase has changed)
|
|
200
|
-
- Do NOT pre-plan the second phase based on the original code state
|
|
201
|
-
|
|
202
|
-
---
|
|
203
|
-
|
|
204
|
-
## 6. Scope Boundary Enforcement
|
|
205
|
-
|
|
206
|
-
During planning, actively enforce scope boundaries to prevent scope creep.
|
|
207
|
-
|
|
208
|
-
### In-Scope Markers
|
|
209
|
-
|
|
210
|
-
Explicitly define what IS in scope:
|
|
211
|
-
- Specific files or directories
|
|
212
|
-
- Specific refactoring operations
|
|
213
|
-
- Specific code smells being addressed
|
|
214
|
-
|
|
215
|
-
### Out-of-Scope Markers
|
|
216
|
-
|
|
217
|
-
Explicitly define what is NOT in scope:
|
|
218
|
-
- New features (redirect to `feature-planner`)
|
|
219
|
-
- Bug fixes (redirect to `bug-planner`)
|
|
220
|
-
- Performance optimization that changes behavior
|
|
221
|
-
- Database schema changes (requires migration planning)
|
|
222
|
-
- API contract changes (requires consumer coordination)
|
|
223
|
-
|
|
224
|
-
### Scope Creep Detection
|
|
225
|
-
|
|
226
|
-
Flag and discuss with the user when:
|
|
227
|
-
- A refactoring item implies new functionality
|
|
228
|
-
- An item requires changing external interfaces
|
|
229
|
-
- An item's description includes "also add" or "while we're at it"
|
|
230
|
-
- An item's acceptance criteria describe new behavior, not preserved behavior
|