litclaude-ai 0.3.6 → 0.3.8

package/plugins/litclaude/skills/refactor/SKILL.md

@@ -9,19 +9,36 @@ Use this skill for behavior-preserving restructuring. A refactor changes shape,
 not observable behavior. If behavior changes, it is a feature or bug fix and
 needs its own RED test.
 
-## Refactor Contract
+This skill runs as a disciplined, phased workflow. The phases below are the
+authoritative order: characterize, gate the intent, map the codebase, assess
+coverage, execute step-by-step with verification, then sweep for regressions.
+Do not skip phases. Refactoring without tests is reckless; refactoring without
+understanding the impact zone is destructive.
 
-Before editing:
+## Tooling in Claude Code terms
 
-- Name the behavior that must remain unchanged.
-- Write or identify characterization tests.
-- Capture the current output, CLI behavior, hook JSON, or plugin manifest shape.
-- Decide the smallest cohesive unit to move, split, rename, or simplify.
+- **LSP tool**: use it for precise analysis and safe edits — go-to-definition to
+  grasp context, find-references to map every call site before touching a
+  symbol, document/workspace symbols to outline a file, rename to move symbols
+  across the workspace, and diagnostics after every change.
+- **Subagents (Agent/Task, namespaced `litclaude:*`)**: fan out read-only
+  exploration in parallel. Each subagent receives a self-contained brief —
+  children do not see prior conversation, so inline the target, the relevant
+  diffs, the constraints, and the exact report shape you want back.
+- **Bash**: run the project's existing test, type-check, lint, and build
+  commands. Detect them from the repo; do not assume a runner.
+- **TodoWrite**: keep the phase list and the per-step plan visible and updated
+  in real time.
+
+---
 
-## Characterization First
+## Phase 0: Characterization First (MANDATORY)
 
-A characterization test pins current behavior before changes. It should assert
-the contract, not incidental formatting. For LitClaude, good contracts include:
+A characterization test pins current behavior before any change. It asserts the
+contract, not incidental formatting. Write or identify these tests before you
+touch code, and record that they pass against the unchanged tree.
+
+For LitClaude, good contracts include:
 
 - CLI command succeeds or fails with a controlled message.
 - hook JSON contains the expected activation context.
@@ -29,11 +46,326 @@ the contract, not incidental formatting. For LitClaude, good contracts include:
 - install state preserves unrelated Claude settings.
 - docs contain required install and publish guidance.
 
-Run the characterization test before refactoring and record that it passes.
+Run the characterization test before refactoring and record that it passes. If
+no such test exists and the target lacks coverage, Phase 3 decides whether you
+add one first, pause, or block.
+
+The refactor contract you commit to before editing:
+
+- Name the behavior that must remain unchanged.
+- Capture the current output, CLI behavior, hook JSON, or manifest shape.
+- Decide the smallest cohesive unit to move, split, rename, or simplify.
+
+---
+
+## Phase 1: Intent Gate
+
+Before any action, classify and validate the request.
+
+### 1.1 Parse the request type
+
+| Signal | Classification | Action |
+|--------|----------------|--------|
+| Specific file/symbol named | Explicit | Proceed to Phase 2 |
+| "Refactor X to Y" | Clear transformation | Proceed to Phase 2 |
+| "Improve", "Clean up", "Modernize" | Open-ended | ASK: "What specific improvement?" |
+| Ambiguous scope | Uncertain | ASK: "Which modules or files?" |
+| Missing desired outcome | Incomplete | ASK: "What is the target shape?" |
+
+### 1.2 Validate understanding
+
+Confirm all of the following before proceeding:
+
+- [ ] Target is clearly identified.
+- [ ] Desired outcome is understood.
+- [ ] Scope is defined (file / module / project).
+- [ ] Success criteria can be articulated.
+
+If any item is unclear, stop and ask one focused clarifying question:
+
+```
+I want to confirm the refactoring goal.
+
+What I understood: [interpretation]
+What I am unsure about: [specific ambiguity]
+
+Options:
+1. [Option A] - [implications]
+2. [Option B] - [implications]
+
+My recommendation: [suggestion with reasoning]
+
+Should I proceed with the recommendation, or would you prefer differently?
+```
+
+### 1.3 Seed the phase todos
+
+Immediately after the request is clear, register the phase list with TodoWrite:
+
+```
+Phase 2: Codebase Analysis - map the target, dependents, tests, conventions
+Phase 3: Codemap - dependency graph + impact-zone risk table
+Phase 4: Coverage Assessment - decide the verification strategy
+Phase 5: Execute - per-step edit -> verify -> revert, with commit checkpoints
+Phase 6: Final Regression Sweep
+```
+
+---
+
+## Phase 2: Codebase Analysis
+
+Mark Phase 2 in_progress.
+
+### 2.1 Parallel exploration with subagents
+
+Fan out read-only `litclaude:*` exploration subagents in parallel. Give each one
+a self-contained brief inlining the target and the exact report shape. Useful
+lanes:
+
+- **Target lane**: find every definition and occurrence of the target — report
+  file paths, line numbers, and usage patterns.
+- **Dependents lane**: find all code that imports, calls, or depends on the
+  target — report dependency chains and import graphs.
+- **Convention lane**: find similar patterns already in the codebase — report
+  analogous implementations and established conventions to follow.
+- **Test lane**: find all test files touching the target — report paths, test
+  names, and coverage indicators.
+- **Architecture lane**: find the module boundaries and design patterns around
+  the target — report layer structure and the patterns in use.
+
+Each subagent runs with its own context. Collect every lane's findings before
+building the codemap.
+
+### 2.2 Direct LSP and search analysis
+
+Alongside subagent results, use the LSP tool directly for precision:
+
+- go-to-definition: where is the symbol defined?
+- find-references (include declaration): every usage across the workspace —
+  this is your authoritative call-site map.
+- document symbols: a hierarchical outline of the file.
+- workspace symbols: search the symbol by name across the project.
+- diagnostics: capture the baseline error/warning state before any edit.
+
+Use Grep for plain-text occurrences the LSP cannot resolve (strings, configs,
+docs). Record the baseline diagnostics — it is the bar every later step must
+hold.
+
+Mark Phase 2 completed once all findings are collected.
+
+---
+
+## Phase 3: Codemap
+
+Mark Phase 3 in_progress.
+
+### 3.1 Build the definitive codemap
+
+From Phase 2 results, construct an explicit map:
+
+```
+## CODEMAP: [TARGET]
+
+### Core files (direct impact)
+- path/to/file.ts:L10-L50 - primary definition
+- path/to/file2.ts:L25    - key usage
+
+### Dependency graph
+[TARGET]
+  imports from:
+    - module-a (types)
+    - module-b (utils)
+  imported by:
+    - consumer-1.ts
+    - consumer-2.ts
+  used by:
+    - handler.ts (direct call)
+    - service.ts (injected dependency)
+
+### Established patterns
+- Pattern A: [description] - used in N places
+- Pattern B: [description] - established convention
+```
+
+### 3.2 Impact-zone risk table
+
+| Zone | Risk | Files affected | Coverage |
+|------|------|----------------|----------|
+| Core | HIGH | N files | xx% |
+| Consumers | MEDIUM | N files | xx% |
+| Edge | LOW | N files | xx% |
+
+### 3.3 Refactoring constraints
+
+From the codemap, write down:
+
+- **MUST follow**: the existing patterns identified above.
+- **MUST NOT break**: critical dependencies and public contracts.
+- **Safe to change**: isolated zones with good coverage.
+- **Requires migration**: any breaking change and who it touches.
+
+Mark Phase 3 completed.
+
+---
+
+## Phase 4: Coverage Assessment (gating)
+
+Mark Phase 4 in_progress.
+
+### 4.1 Detect the test infrastructure
+
+Discover the repo's actual commands — read `package.json` scripts,
+`pyproject.toml` / `pytest.ini`, Go test files, or the equivalent. Do not assume
+a runner.
+
+### 4.2 Assess coverage for the target
+
+Use the Phase 2 test lane plus direct inspection to answer: which test files
+cover this code, what cases exist, are there integration tests, what edge cases
+are pinned, and roughly what fraction is covered.
+
+### 4.3 Choose the verification strategy
+
+| Coverage | Strategy |
+|----------|----------|
+| HIGH (>80%) | Run existing tests after each step. |
+| MEDIUM (50-80%) | Run tests plus add characterization assertions for the gaps. |
+| LOW (<50%) | PAUSE: propose writing characterization tests first. |
+| NONE | BLOCK: refuse the refactor until characterization tests exist. |
+
+When coverage is LOW or NONE, stop and ask:
+
+```
+Test coverage for [TARGET] is [LEVEL].
+Refactoring without adequate tests is unsafe.
+
+Options:
+1. Add characterization tests first, then refactor (recommended)
+2. Proceed with extra caution and manual verification
+3. Abort
+
+Which do you prefer?
+```
+
+### 4.4 Document the verification plan
+
+```
+## VERIFICATION PLAN
+
+Test commands (from this repo):
+- Unit / integration: <actual command>
+- Type check: <actual command>
+- Lint / build: <actual command if relevant>
+
+Per-step checkpoints:
+1. LSP diagnostics -> no new errors versus baseline
+2. Targeted tests -> all pass
+3. Type check -> clean
+
+Regression indicators:
+- [specific test that must keep passing]
+- [behavior that must be preserved]
+- [public contract that must not change]
+```
+
+Mark Phase 4 completed.
+
+---
+
+## Phase 5: Execute (per-step edit -> verify -> revert)
+
+Mark Phase 5 in_progress.
+
+Break the work into atomic steps ordered by dependency. Each step must be
+independently verifiable and independently reversible. Register the steps as
+todos.
+
+### 5.1 Per-step protocol
+
+For every step:
+
+1. Mark the step todo in_progress.
+2. Read the current file state; confirm LSP diagnostics match the baseline.
+3. Execute the smallest change:
+   - **Symbol rename**: use the LSP rename across the workspace, not text
+     search-and-replace.
+   - **Move or extract**: use the Edit tool for precise edits; keep one cohesive
+     unit per step.
+   - **Signature change**: update the definition, then walk every call site from
+     the find-references map.
+4. Verify (MANDATORY):
+   - LSP diagnostics on touched files — clean or equal to baseline.
+   - Run the targeted test command from the verification plan.
+   - Run the type check.
+5. If verification passes, mark the step completed and continue. If it fails,
+   enter the Failure Recovery Protocol.
+
+### 5.2 Failure Recovery Protocol
+
+When any verification fails:
+
+1. **STOP** immediately — do not stack a second change on a broken step.
+2. **REVERT** the failed change to the last known-good state.
+3. **DIAGNOSE** the actual cause (read the failing assertion, the diagnostic,
+   the diff).
+4. Present **OPTIONS** and pick or ask:
+   - Fix the root cause and retry the same step.
+   - Skip the step if it was optional.
+   - Dispatch a read-only `litclaude:*` review subagent — inline the failure,
+     the touched files, and ask for a fix strategy.
+   - Ask the user for guidance.
+
+NEVER proceed to the next step while tests are red.
+
+### 5.3 Commit checkpoints
+
+After each logical group of verified steps, create a checkpoint commit so any
+step is cheap to revert:
+
+```
+git add <changed-files>
+git commit -m "refactor(scope): <what changed and why>"
+```
+
+Do not commit broken code, and do not hide a behavior change inside a refactor
+commit.
+
+Mark Phase 5 completed when every step is done and committed.
+
+---
+
+## Phase 6: Final Regression Sweep
+
+Mark Phase 6 in_progress.
+
+1. Run the full relevant test suite (the real repo command).
+2. Run the full type check.
+3. Run the linter.
+4. Run the build if the project has one.
+5. Run LSP diagnostics across every changed file — all clean.
+6. Run one real-surface scenario if the refactor touched install, hooks, or CLI
+   (a CLI transcript, a hook JSON dump, or a manifest diff). Compare
+   before/after output where practical.
+7. Record cleanup for any spawned resource (subagent runs, temp files, ports).
+
+Summarize:
+
+```
+## Refactoring complete
+
+Changed: <files and what changed>
+Tests: PASS (X/Y)   Type check: CLEAN   Lint: CLEAN   Build: OK
+Behavior: unchanged - characterization tests still green, no new diagnostics.
+```
+
+Mark Phase 6 completed.
+
+---
 
 ## Safe Splits
 
-Split by responsibility:
+Split by responsibility, never by arbitrary line range. Every new file must have
+a clear owner:
 
 - parsing
 - registry/state reads
@@ -43,31 +375,63 @@ Split by responsibility:
 - docs-only policy
 - QA scripts
 
-Avoid splitting by arbitrary line ranges. A new file must have a clear owner.
+---
+
+## Critical Rules
+
+### NEVER
+- Skip the LSP diagnostics check after a change.
+- Proceed with failing or red tests.
+- Edit a symbol without first mapping its call sites (find-references).
+- Suppress type or lint errors to make a step pass.
+- Rename a public CLI command without a compatibility alias.
+- Change plugin keys such as `litclaude@litclaude-ai` silently.
+- Alter install paths without migration tests.
+- Delete or weaken tests to make a refactor pass.
+- Commit broken code or hide a behavior change in a refactor commit.
 
-## Prohibited Moves
+### ALWAYS
+- Characterize before changing.
+- Map the impact zone before editing.
+- Preview a structural change before applying it.
+- Verify after every step.
+- Follow the established patterns the codemap surfaced.
+- Keep the todos and phase state current.
+- Commit at logical checkpoints.
+- Keep the package `files` allowlist in sync when files move.
 
-- Do not rename public CLI commands without compatibility aliases.
-- Do not change plugin keys such as `litclaude@litclaude-ai` silently.
-- Do not alter install paths without migration tests.
-- Do not hide behavior changes inside refactor commits.
-- Do not delete tests to make a refactor pass.
+### ABORT and consult the user
+- Coverage is NONE for the target and the user declined characterization tests.
+- A change would break a public API or contract.
+- The scope is still unclear after one clarifying question.
+- Three consecutive verification failures on the same step.
+- A user-defined constraint would be violated.
+
+---
 
-## Verification
+## Deprecated Libraries and Migration
 
-After refactoring:
+When you hit a deprecated method or API during a refactor:
 
-1. Run targeted characterization tests.
-2. Run the full relevant suite.
-3. Run one real-surface scenario if the refactor touches install, hooks, or CLI.
-4. Compare before/after outputs where practical.
-5. Record cleanup for spawned resources.
+1. Dispatch a read-only research `litclaude:*` subagent (or use Context7 docs) to
+   find the recommended modern replacement before editing.
+2. Do NOT auto-upgrade to the latest version unless the user explicitly asked for
+   a migration — a behavior-preserving refactor must not silently change runtime
+   behavior.
+3. If the user did request a migration, fetch the current API docs first, then
+   write characterization tests for the old behavior, then migrate step by step
+   under Phase 5.
+
+---
 
 ## Review Checklist
 
-- Public behavior unchanged.
+- Public behavior unchanged; characterization tests still green.
 - Error messages still actionable.
 - Package `files` allowlist still includes moved files.
 - Docs still reference the right paths.
 - Tests fail if the behavior regresses.
 - No generated or user-owned state was rewritten unexpectedly.
+
+Refactoring without tests is reckless. Refactoring without understanding the
+impact zone is destructive. This workflow ensures you do neither.