levnikolaevich/ln-831-oss-replacer

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. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

ln-831-oss-replacer

Type: L3 Worker Category: 8XX Optimization

Executes OSS replacement plans from ln-645-open-source-replacer. For each custom module with a viable OSS alternative: install package, rewrite imports, run verification, then keep or discard atomically.

---

Overview

| Aspect | Details | |--------|---------| | Input | Migration plan from audit output or a target module | | Output | Replaced modules plus a machine-readable modernization summary | | Companion | ln-645-open-source-replacer identifies candidates, ln-831 executes them |

---

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 replacement | | Package manager available | Yes | Block replacement | | Workspace baseline safe | Yes | In managed runs coordinator already prepared it; in standalone runs protect rollback locally |

MANDATORY READ: Load shared/references/ci_tool_detection.md for test detection. MANDATORY READ: Load shared/references/mcp_tool_preferences.md and shared/references/mcp_integration_patterns.md

Use hex-line first for local code edits and reads when available, and use hex-graph first when cross-file reference checks materially improve replacement safety. If MCP is unavailable, unsupported, or not indexed, continue with built-in Read/Grep/Glob/Bash and state the fallback in the summary.

Runtime Coordination

Managed runs receive deterministic runId and exact summaryArtifactPath from ln-830. Standalone runs remain supported; if runtime arguments are omitted, generate a standalone run-scoped artifact before returning.

---

Phase 1: Load Migration Plan

From audit report, extract:

| Field | Description | |-------|-------------| | custom_module | Path to the custom implementation | | loc | Lines of code in the custom module | | oss_package | Recommended OSS replacement | | confidence | HIGH, MEDIUM, or LOW | | api_mapping | Custom function to OSS equivalent |

If no audit report exists, analyze the target module and search Context7 or Ref for viable OSS alternatives.

MANDATORY READ: Load shared/references/research_tool_fallback.md

---

Phase 2: Prioritize Replacements

| Priority | Criteria | |----------|----------| | 1 | HIGH confidence and >200 LOC | | 2 | HIGH confidence and 100-200 LOC | | 3 | MEDIUM confidence and >200 LOC | | 4 | MEDIUM confidence and 100-200 LOC | | Skip | LOW confidence |

---

Phase 3: Replace Loop (Keep/Discard)

Per-module cycle:

FOR each replacement candidate:
  1. INSTALL: add the OSS package
  2. REWRITE: update imports and call sites using api_mapping
  3. VERIFY: run tests
     IF tests fail -> DISCARD and revert all changes for this candidate
  4. KEEP: only after verification passes
  5. DELETE: remove old custom module after keep
  6. LOG: record result for the final report

Stop conditions:

| Condition | Action | |-----------|--------| | All candidates processed | Stop and report | | 3 consecutive discards | Warn and stop for manual review | | Test infrastructure itself breaks | Stop and revert to last known good state | | No candidates above confidence threshold | Stop and report no viable replacements |

Atomic revert on discard:

| Step | Revert Action | |------|---------------| | Package installed | Uninstall it | | Files modified | Restore module files | | Lock file changed | Restore lock file |

Safety rules:

| Rule | Description | |------|-------------| | One module at a time | Never replace multiple modules simultaneously | | No API signature drift | Public interfaces must stay compatible | | Tests required | Skip modules with no coverage when risk is unclear | | Confidence gate | Skip LOW-confidence replacements |

---

Phase 4: Report Results

| 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 | Skipped due to low confidence or missing tests | | loc_removed | Total lines of custom code removed | | packages_added | New OSS packages installed | | details[] | Per replacement summary | | artifact_path | Durable worker report path, if written |

---

Configuration

Options:
  audit_report: "docs/project/codebase_audit.md"
  target_module: ""
  min_confidence: "MEDIUM"
  run_tests: true
  require_test_coverage: true
  delete_old_module: true

---

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Package not found | OSS package name changed | Search current docs for the new package name | | API mismatch | Mapping differs from real library API | Query docs and retry only if fix is clear | | Circular dependency | New package conflicts with current architecture | Skip and report manual follow-up | | No test coverage | Too risky for automated replacement | Skip and report |

---

References

• ../ln-645-open-source-replacer/SKILL.md
• shared/references/ci_tool_detection.md
• shared/references/research_tool_fallback.md

---

Runtime Summary Artifact

MANDATORY READ: Load shared/references/coordinator_summary_contract.md

Emit a modernization-worker summary envelope.

Managed mode:

• ln-830 passes deterministic runId and exact summaryArtifactPath
• write the summary to the provided summaryArtifactPath

Standalone mode:

• omit runId and summaryArtifactPath
• write .hex-skills/runtime-artifacts/runs/{run_id}/modernization-worker/ln-831--{identifier}.json

Monitor (2.1.98+): For install + test verification loops expected >30s, use Monitor. Fallback: Bash(run_in_background=true).

Definition of Done

• [ ] Migration plan loaded or target module analyzed
• [ ] Candidates prioritized by confidence and code-reduction value
• [ ] Each replacement executed atomically with keep/discard verification
• [ ] Discarded replacements fully reverted
• [ ] Kept replacements remove old custom code only after verification passes
• [ ] Report captures applied, discarded, skipped replacements, and LOC removed
• [ ] modernization-worker summary artifact written to the managed or standalone path

---

Version: 1.0.0 Last Updated: 2026-03-08