levalencia Paths: File paths (
shared/,references/,../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.
ln-831-oss-replacer
Type: L3 Worker Category: 8XX Optimization Parent: ln-830-code-modernization-coordinator
Executes OSS replacement plans from ln-645-open-source-replacer auditor. For each custom module with an OSS alternative: install package, rewrite imports, run tests, keep or discard atomically.
Overview
| Aspect | Details |
|---|---|
| Input | Migration plan from docs/project/codebase_audit.md (ln-645 section) OR target module |
| Output | Replaced modules, migration report |
| Companion | ln-645-open-source-replacer (finds candidates) → ln-831 (executes replacement) |
Workflow
Phases: Pre-flight → Load Plan → Prioritize → Replace Loop → Report
Phase 0: Pre-flight Checks
| Check | Required | Action if Missing |
|---|---|---|
| Migration plan OR target module | Yes | Block replacement |
| Test infrastructure | Yes | Block (need tests for verification) |
| Package manager available | Yes | Block (need to install OSS packages) |
| Git clean state | Yes | Block (need clean baseline for revert) |
MANDATORY READ: Load shared/references/ci_tool_detection.md — use Test Frameworks section for test detection.
Worktree & Branch Isolation
MANDATORY READ: Load shared/references/git_worktree_fallback.md — use ln-831 row.
Phase 1: Load Migration Plan
From Audit Report
Read docs/project/codebase_audit.md, extract ln-645 findings:
| Field | Description |
|---|---|
| custom_module | Path to custom implementation |
| loc | Lines of code in custom module |
| oss_package | Recommended OSS replacement |
| confidence | How well OSS covers functionality (HIGH/MEDIUM/LOW) |
| api_mapping | Custom function → OSS equivalent |
From Target Module
If no audit report: analyze target module, search Context7/Ref for OSS alternatives.
MANDATORY READ: Load shared/references/research_tool_fallback.md for MCP tool chain.
Phase 2: Prioritize Replacements
| Priority | Criteria |
|---|---|
| 1 (highest) | HIGH confidence + >200 LOC (max code reduction) |
| 2 | HIGH confidence + 100-200 LOC |
| 3 | MEDIUM confidence + >200 LOC |
| 4 | MEDIUM confidence + 100-200 LOC |
| Skip | LOW confidence (too risky for automated replacement) |
Phase 3: Replace Loop (Keep/Discard)
Per-Module Cycle
FOR each replacement candidate (R1..RN):
1. INSTALL: Add OSS package
npm install {package} / dotnet add package / pip install
2. REWRITE: Update imports + call sites using api_mapping
3. VERIFY: Run tests
IF tests FAIL → DISCARD (revert ALL: uninstall package, restore files) → next
4. TESTS PASS → KEEP
5. DELETE: Remove old custom module (only after keep)
6. LOG: Record replacement for report
Atomic Revert on Discard
| Step | Revert Action |
|---|---|
| Package installed | Uninstall: npm uninstall / dotnet remove package / pip uninstall |
| Files modified | git checkout -- {modified_files} |
| Lock file changed | git checkout -- {lock_file} |
Safety Rules
| Rule | Description |
|---|---|
| One module at a time | Never replace multiple modules simultaneously |
| No API signature changes | Public API of replaced module must stay compatible |
| Tests required | Skip module if no tests cover it (too risky) |
| Confidence gate | Skip LOW confidence replacements |
Phase 4: Report Results
Report Schema
| Field | Description |
|---|---|
| source | Audit report path or target module |
| candidates_total | Total replacement candidates |
| replacements_applied | Successfully replaced modules |
| replacements_discarded | Failed replacements with reasons |
| replacements_skipped | LOW confidence / no test coverage |
| loc_removed | Total lines of custom code removed |
| packages_added | New OSS packages installed |
| details[] | Per-replacement: module, package, LOC removed |
Configuration
Options:
# Source
audit_report: "docs/project/codebase_audit.md"
target_module: ""
# Confidence
min_confidence: "MEDIUM" # MEDIUM | HIGH
# Verification
run_tests: true
# Safety
require_test_coverage: true # Skip modules with no tests
delete_old_module: true # Delete custom module after successful replacement
Error Handling
| Error | Cause | Solution |
|---|---|---|
| Package not found | OSS package name changed | Search Context7/Ref for current name |
| API mismatch | OSS API differs from mapping | Query docs for correct API, attempt fix |
| Circular dependency | New package conflicts | Skip replacement, log as manual |
| No test coverage | Custom module untested | Skip (too risky for automated replacement) |
References
../ln-645-open-source-replacer/SKILL.md(companion: finds candidates)shared/references/ci_tool_detection.md(test detection)shared/references/research_tool_fallback.md(MCP tool chain)
Definition of Done
- Migration plan loaded from audit report or target module analyzed
- Candidates prioritized by confidence + LOC
- Each replacement applied atomically: install → rewrite → test → keep/discard
- Discarded replacements fully reverted (package + files + lock)
- Kept replacements: old custom module deleted
- Report returned with candidates total, applied, discarded, LOC removed
Version: 1.0.0 Last Updated: 2026-03-08