document-haness/.agents/skills/refactoring-from-analysis/SKILL.md

name, description

name	description
refactoring-from-analysis	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.