/openlore-plan-refactor

name: openlore-plan-refactor
description: Identify a high-priority refactoring target, assess its blast radius, and write .openlore/refactor-plan.md without changing code. Use when asked to plan or prioritize a refactor.

openlore: Plan Refactor

When to use this skill

Trigger this skill whenever the user asks to **plan a refactoring** on a codebase, with phrasings like:

• "plan a refactoring of X"
• "analyze my code and prepare a refactor plan"
• "generate a refactoring plan"
• "I want to refactor this function / this file"
• explicit command `/openlore-plan-refactor`

**This skill modifies no code files.** It only produces `.openlore/refactor-plan.md`. To apply the plan, use the `openlore-execute-refactor` skill.

---

⚠️ Fundamental principle — each change is a complete mini-development

**The plan must be written so that every entry in the change sequence is independently executable and testable.**

Each change = one atomic edit → one diff verification → one full test run → ✅ or rollback.

This is not a final gate at the end. Testing is a mandatory sub-step after **every single change**. The plan must make this cycle explicit and impossible to skip.

**For small models (< 13B parameters)**: each change must touch at most **50 contiguous lines** in the source file. If a logical extraction exceeds this limit, split it into smaller sub-changes, each with its own test gate.

---

User-specified target — shortcut path

If the user has already named a specific file or function to refactor:

• **Skip** Steps 2, 3, and 3b (discovery is not needed).
• **Do not skip** Steps 3c, 4, 5, 6, and 6b — coverage check and impact analysis are mandatory regardless of how the target was chosen.
• Jump directly to Step 3c using the user-provided target.

---

Step 1 — Confirm the project directory

Ask the user which project to analyze, or confirm the current workspace root.

---

Step 2 — Run static analysis

Call the openlore MCP tool `analyze_codebase` with `{"directory": "$DIRECTORY"}`.

If a recent analysis already exists, skip unless the user explicitly requests a fresh run.

---

Step 3 — Get the refactoring report

Call the openlore MCP tool `get_refactor_report` with `{"directory": "$DIRECTORY"}`.

Present the top 5 candidates:

| Function | File | Issues | Priority score | |---|---|---|---|

---

Step 3b — Check for duplicate code

Call the openlore MCP tool `get_duplicate_report` with `{"directory": "$DIRECTORY"}`.

If a top candidate appears in a clone group, prepend a **deduplication note** to the plan: > "⚠️ `<function>` has N near-clones. Consolidate them first to reduce the blast radius of this refactor."

---

Step 3c — Check test coverage

Before presenting a choice to the user, check test coverage for the files containing the candidates. Detect the coverage tool from the project:

| Ecosystem | Command | |---|---| | Node.js | `npm test -- --coverage --collectCoverageFrom="<files>"` | | Python | `pytest --cov=<module> --cov-report=term-missing` | | Rust | `cargo tarpaulin --include-files <files>` | | Go | `go test -cover ./...` |

Enrich the candidate table:

| Function | File | Priority | Coverage | |---|---|---|---| | ... | ... | ... | 72% ✅ / 35% ⚠️ / 0% 🚫 |

**Thresholds:**

| Coverage | Badge | Meaning | |---|---|---| | ≥ 70% lines | ✅ | Safe to refactor | | 40–69% lines | ⚠️ | Write characterisation tests first | | < 40% lines | 🛑 | Strongly discouraged | | 0% (no tests) | 🚫 | Blocked — propose a test harness first |

If **all candidates are below 40%**: > "Every high-priority target has insufficient test coverage (< 40%). I recommend writing a minimal test harness for at least one target before proceeding. Would you like me to suggest test cases based on the function signatures?"

---

Step 4 — Get minimal context + analyze impact

Get the condensed view of the target function (callers, callees, body, test coverage in one call):

Call the openlore MCP tool `get_minimal_context` with `{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME"}`.

**What to read before deciding whether to proceed:**

• `function.riskLevel` — `"high"` (fanIn ≥ 30 or fanOut ≥ 15) means up to 24 callers/callees shown. Read all — they are all in scope for this refactor.
• `callers[*].callType` — all `"awaited"` = async interface frozen; extracting or splitting requires updating every call site. `"direct"` / `"method"` = more portable.
• `testedBy[*].confidence` — `"called"` = direct test, safe to refactor under. `"imported"` only = `vi.mock()` can neutralize it; write a characterisation test **before** refactoring.

Then get the full impact analysis:

Call the openlore MCP tool `analyze_impact` with `{"directory": "$DIRECTORY", "symbol": "$FUNCTION_NAME"}`.

Note: risk score (0–100), recommended strategy (`extract` / `split` / `facade` / `delegate`), top 5 upstream callers and downstream callees.

**If `riskLevel` is `"high"` or impact risk score ≥ 60**, check the cluster to set refactor scope:

Call the openlore MCP tool `get_cluster` with `{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME"}`.

Read `stats.clusterDensity`:

• `< 0.05` — sparse; extract the target independently, others not in scope
• `0.05–0.15` — moderate; include functions in `internalCallGraph` that call the target in the plan's risk section
• `> 0.15` — dense; refactor the whole cluster together or not at all; add all members to affected-files list

---

Step 5 — Visualise the call neighbourhood

Call the openlore MCP tool `get_subgraph` with:

{"directory": "$DIRECTORY", "functionName": "$FUNCTION_NAME", "direction": "both", "format": "mermaid"}

Show the Mermaid diagram to the user.

---

Step 6 — Find safe entry points (bottom-up)

Call the openlore MCP tool `get_low_risk_refactor_candidates` with:

{"directory": "$DIRECTORY", "filePattern": "$TARGET_FILE", "limit": 5}

Cross-reference with the subgraph from Step 5: a good first extraction candidate alr