35 lines
2.5 KiB
Markdown
35 lines
2.5 KiB
Markdown
---
|
|
name: refactoring-from-analysis
|
|
description: Use when a completed codebase analysis should be turned into one bounded, evidence-backed refactoring WorkItem and implemented in isolation.
|
|
---
|
|
|
|
# Refactoring From Analysis
|
|
|
|
## Goal
|
|
|
|
Use `docs/<프로젝트>` as high-value context for a bounded refactor while treating the current `<분석 대상 저장소>` as source truth. One execution handles at most one WorkItem.
|
|
|
|
## Required sequence
|
|
|
|
1. Read `<분석 대상 저장소>/refactor-queue.yaml` and the selected `docs/<프로젝트>/refactor/<project>/<item>/work-item.json`.
|
|
2. Read the project's completed `document-detail` analysis and source anchors cited by the WorkItem.
|
|
3. Confirm the analysis queue entry is `COMPLETE`, its completed source revision equals current repository HEAD, and the source working tree is clean. Otherwise do not refactor.
|
|
4. Re-check the finding against current code. If it no longer exists, mark the item `REJECTED` with evidence; do not force a change.
|
|
5. Read `references/refactor-queue-contract.md`, `references/work-item-contract.md`, `references/type-strategies.md`, and `references/evidence-contract.md`. For `PERFORMANCE`, also read `references/performance-evidence-contract.md`.
|
|
6. Create/use an isolated Git worktree/branch for the WorkItem. Never implement directly in the analysis source checkout.
|
|
7. Follow the strategy selected by `type` and `scope`.
|
|
8. Preserve raw verification evidence under `docs/<프로젝트>/refactor/<project>/<item>/`.
|
|
9. Run `scripts/verify-refactor-work-item.py <item-dir>` before moving to `WAITING_APPROVAL`.
|
|
|
|
## Performance ordering rule
|
|
|
|
For `PERFORMANCE`, the state/operation sequence is mandatory:
|
|
|
|
`READY → BASELINING → baseline capture at analysisRevision → IN_PROGRESS → source change → VERIFYING → after capture under the same measurement contract → comparison → functional regression checks → WAITING_APPROVAL`.
|
|
|
|
`IN_PROGRESS` means source-changing work is now allowed, so a performance item may not enter it until baseline raw evidence and baseline metadata exist. No source-changing refactor begins before that baseline exists. If comparable measurement conditions cannot be maintained, mark the item `BLOCKED` or the comparison `INCOMPARABLE`; never claim improvement.
|
|
|
|
## Bounded change rule
|
|
|
|
If a WorkItem expands beyond its declared scope or uncovers an independent problem, stop expanding the diff. Create another candidate WorkItem instead. A large project or module is not permission for a large refactor item.
|