openlore-plan-refactor
Skill359 starsChanged 6 months agoMITView on GitHub
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.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- clay-good/OpenLoreword for word, first seen May 29, 2026
Other versions1 project uses a version of this.
Word for word · 1
- clay-good/OpenLore★ 365100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- openlore-analyze-codebaseSkill
- openlore-brainstormSkill
- openlore-debugSkill
- openlore-execute-refactorSkill
- openlore-generateSkill
- openlore-implement-storySkill
- openlore-orientSkill
- openlore-repairSkill
- openlore-review-changesSkill
- openlore-write-testsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. About 0 are common, 13 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
If a logical extraction exceeds this limit, split it into smaller sub-changes, each with its own test gate.
- Distinctive: line 38
If the user has already named a specific file or function to refactor:
- Distinctive: line 47
Ask the user which project to analyze, or confirm the current workspace root.
- Very specific: line 53
Call the openlore MCP tool analyze_codebase with {"directory": "$DIRECTORY"}.
- Distinctive: line 55
If a recent analysis already exists, skip unless the user explicitly requests a fresh run.
- Distinctive: line 74
If a top candidate appears in a clone group, prepend a deduplication note to the plan:
- Distinctive: line 81
Before presenting a choice to the user, check test coverage for the files containing the candidates.
- Distinctive: line 105
If all candidates are below 40%:
- Very specific: line 140
Call the openlore MCP tool get_subgraph with:
- Distinctive: line 162
Before designing the change sequence, identify where extracted functions should land.
- Distinctive: line 181
If a logical extraction requires moving more than 50 lines in one pass, split it into sub-changes:
- Distinctive: line 295
Always read the source file to confirm exact line numbers
- Distinctive: line 296
Never leave a section empty or as "TBD"
- Distinctive: line 298
Prefer candidates with higher coverage when scores are otherwise close
- Distinctive: line 299
If the user does not pick a target, default to the top candidate
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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 scope0.05–0.15— moderate; include functions ininternalCallGraphthat 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 already appears as a callee of the target function.
Step 6b — Find insertion points for extracted helpers
Before designing the change sequence, identify where extracted functions should land. This avoids creating helpers in the wrong file or layer.
Call the openlore MCP tool suggest_insertion_points with:
{"directory": "$DIRECTORY", "query": "extract helper from $FUNCTION_NAME", "limit": 5}For each candidate, note its role and strategy. Prefer candidates that already call into — or are called by — the target function (visible in the Step 5 subgraph).
Step 7 — Design the change sequence
Design an ordered sequence of atomic changes based on the strategy from Step 4.
Size constraint (mandatory for small models)
Each change must touch at most 50 contiguous lines in the source file. If a logical extraction requires moving more than 50 lines in one pass, split it into sub-changes:
- Sub-change A: extract the inner block (≤ 50 lines)
- Sub-change B: extract the outer wrapper (≤ 50 lines) Each sub-change gets its own test gate. Never group two sub-changes before testing.
Each change must specify
- What: the exact block to move (line range or description)
- Lines touched: estimated count in source file — must be ≤ 50
- New name: the function or method name to give it
- Target file: existing or new file (with justification)
- Target class (if applicable)
- Call sites to update: list each
file:line - Test gate: exact test command to run after this change
Mini-development cycle per change (write this explicitly in the plan)
READ plan entry → EDIT (targeted, ≤ 50 lines) → DIFF verify → TEST
├─ green → mark ✅, next change
└─ red → git checkout HEAD -- <file>, diagnose, retry
after 3 failed retries → STOP, report to userThe plan must show this cycle in the change sequence, not just in a footnote.
Rules per strategy:
| Strategy | Rule |
split | Decompose into N sub-functions in the same file unless they clearly belong elsewhere |
extract | Place in the nearest cohesive module or create a new file if none exists |
facade | Keep the original signature, delegate to smaller functions; companion module if > 300 lines |
delegate | Move ownership logic to callers; update every caller file in the upstream chain |
Present the full sequence and wait for confirmation before writing the plan file.
Step 8 — Write .openlore/refactor-plan.md
Fill every section — leave nothing as "TBD".
# Refactor Plan
Generated: <ISO date>
Workflow: /openlore-plan-refactor → /openlore-execute-refactor
## Target
- **Function**: <n>
- **File**: <relative path>
- **Lines**: <start>–<end>
- **Risk score**: <0–100>
- **Strategy**: <extract | split | facade | delegate>
- **Priority score before refactor**: <value>
## Why
- <issue 1>
- <issue 2>
## Callers (upstream — must not break)
| Caller | File |
|---|---|
## Callees (downstream — candidates for extraction)
| Callee | File |
|---|---|
## Coverage baseline
- **File**: <target file>
- **Coverage**: <X>% lines, <Y>% branches
- **Status**: ✅ safe / ⚠️ caution / 🛑 discouraged
- **Test command**: <exact command>
## Change sequence
Each change is a complete mini-development: edit → diff → test → ✅ or rollback.
Never advance to the next change without a green test gate.
### Change 1 — <short label>
- **What**: extract lines <start>–<end> (logic: <one-line description>)
- **Lines touched in source**: ~<N> lines (must be ≤ 50)
- **New function name**: `<n>`
- **Target file**: `<path>` (<new file | existing file — reason>)
- **Target class**: `<ClassName>` or none
- **Call sites to update**: <list each file:line>
- **Expected diff**: +<N> lines in <target file>, -<M> lines in <source file>
- **Test gate**: `<exact test command>`
- **Retry limit**: 3 attempts — if still red after 3, stop and report
### Change 2 — <short label>
...
## Acceptance criteria
- Priority score drops below <target score> in `get_refactor_report`
- Function exits the top-5 list
- Full test suite passes (green)
- `git diff --stat` shows only the expected files
## Restore point
Hash: <to be filled by the execute workflow>Once the file is written, call record_decision with the target, strategy, rationale,
consequences, and affected files so the planned architectural choice enters the decisions
workflow. Then report:
"Plan written to
.openlore/refactor-plan.md. Review it, then run/openlore-execute-refactorto apply the changes."
Absolute constraints
- No code modifications in this workflow
- Always read the source file to confirm exact line numbers
- Never leave a section empty or as "TBD"
- Each change in the plan must include a test gate and a ≤ 50-line scope
- Prefer candidates with higher coverage when scores are otherwise close
- If the user does not pick a target, default to the top candidate
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

