Generate structured refactoring plans from file similarity analysis.
When to Use
- User asks to plan a refactoring
- User wants to reduce code duplication
- User asks "what should I consolidate?"
- Before a large-scale code cleanup
- After writing new code — dogfood to catch accidental duplication
Usage
# Basic refactoring plan
indexion plan refactor <path>
With higher similarity threshold (stricter matches)
indexion plan refactor --threshold=0.8
Structured plan with phases and checklistsindexion plan refactor --style=structured --name=
Choose similarity strategyindexion plan refactor --strategy=tfidf indexion plan refactor --strategy=ncd indexion plan refactor --strategy=hybrid
GitHub Issue formatindexion plan refactor --format=github-issue
Filter filesindexion plan refactor --include='.mbt' --exclude='_test.mbt'
Output to fileindexion plan refactor -o=refactor-plan.md
Multiple directoriesindexion plan refactor src/ cmd/indexion/
## Options
| Option | Default | Description |
|--------|---------|-------------|
| `--threshold=FLOAT` | 0.7 | Minimum similarity threshold |
| `--strategy=NAME` | hybrid | Similarity strategy: hybrid, tfidf, ncd |
| `--style=STYLE` | raw | Output style: raw, structured |
| `--format=FORMAT` | md | Output format: md, json, text, github-issue |
| `--name=NAME` | — | Project name (for structured style) |
| `--include=PATTERN` | — | Include pattern (repeatable) |
| `--exclude=PATTERN` | — | Exclude pattern (repeatable) |
| `-o, --output=FILE` | stdout | Output file path |
| `--specs-dir=DIR` | kgfs | KGF specs directory |
## Dogfooding Workflow (Proven)
This workflow was validated by using indexion on itself to eliminate 10+
duplicate utility functions and resolve a circular dependency.
### Step 1: Detect duplicates
```bash
# Find code duplicates above 90% (high-confidence matches)
indexion plan refactor --threshold=0.9 \
--include='*.mbt' --exclude='*_wbtest.mbt' \
--exclude='*moon.pkg*' --exclude='*pkg.generated*' \
cmd/indexion/
Step 2: Analyze the output
Focus on three sections:
Duplicate Code Blocks — line-level identical code between files:
- Identical utility functions → extract to
@commonor shared module - Same logic with different names → unify
Function-Level Duplicates — structurally similar functions (TF-IDF on function bodies):
- Cross-file: same function copied between packages → extract to SoT
- Same-file: nearly identical functions → parameterize into one
Same-file duplicates — functions within one file that are 90%+ similar:
- These are the highest-value targets (easiest to fix, clearest wins)
- Example:
get_global_data_dir ≈ get_global_cache_dir→ extractresolve_os_dir
Step 3: Use grep to trace references before fixing
# Find all references to a type/function before moving it
indexion grep "TypeIdent:TfidfEmbeddingProvider" src/
# Find all functions named "substr" to plan consolidation
indexion grep --semantic=name:substr src/
Step 4: Fix and verify
After consolidating duplicates, re-run with the same threshold to confirm they no longer appear:
indexion plan refactor --threshold=0.9 --include='*.mbt' ...
Step 5: Lower threshold and iterate
# After fixing 90%+ duplicates, look for 85%+ matches
indexion plan refactor --threshold=0.85 --include='*.mbt' ...
What Remains After Cleanup
When all actionable duplicates are fixed, you'll see only these in the output:
- Platform stubs (
native.mbt/stub.mbt) — intentional platform branching - Type method similarity (
to_stringon different types) — different types, same pattern - CLI command boilerplate (
command()functions) — @argparse API pattern, not duplication - Semantic-but-different functions (
is_disqualifying_keyword≈is_skip_token) — different purpose
These are signals to stop iterating, not bugs to fix.
Tips
- Exclude noise: Always exclude
*_wbtest.mbt,*moon.pkg*,*pkg.generated*to focus on actual code duplication rather than config/test similarity. - Start high: Begin with
--threshold=0.9and work down. Low thresholds produce huge result sets that are hard to act on. - Use grep first:
indexion grep --semantic=name:Xfinds all functions with a specific name.grep --semantic=proxyfinds wrappers. Use for targeted investigation before running the full plan. - Circular dependencies: If
plan refactorshows cross-package duplication caused by circular imports, useindexion grep "TypeIdent:X"to map all references, then move the type to break the cycle (as was done withSentence→segmentation/types). - Combine with explore: Use
indexion explore --format=listfirst to get a quick similarity overview, then useplan refactorfor actionable detail.