donaldfilimon/abi / .agents/skills/refactor
refactor
VerifiedPlan, execute, and validate a codebase modernization or refactor with clean-slate thinking while preserving semantics. Use when the user asks how to approach a rewrite vs incremental change or what the risk is (strategy), is ready to apply a refactor plan safely (implementation), or asks whether a refactor broke anything or is complete (validation).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.7 KB |
| references/implementation-playbook.md | markdown | 3.0 KB |
| references/strategy-guide.md | markdown | 1.3 KB |
| references/validation-checklist.md | markdown | 912 B |
references/implementation-playbook.md
View on GitHub# Implementation Playbook
Safe execution steps for clean-slate modernization. Pair with the validation phase of the `refactor` skill after each significant change.
## Preconditions
1. Analysis checklist complete (targets + evidence).
2. Strategy chosen (direct / phased strangler / parallel modern impl).
3. Baseline gate green (run the project's narrowest covering gate; in abi, `./tools/check.sh` or a scoped `./tools/cargo.sh test -p <crate> ... < /dev/null`).
4. Frozen surfaces listed — do **not** resurrect legacy CLI names or invent MCP tools.
## Execution loop
### 1. Characterize before rewrite
- Prefer existing contract/unit tests that drive the **shipped** path.
- If missing, add a characterizing test that fails on wrong behavior without re-implementing the code under test.
- Capture baseline output when behavior is observational (CLI smoke, docs structure).
### 2. One semantic change at a time
- Prefer parallel files (`foo_v2.rs` / extracted helper) over in-place rewrites of hot contracts.
- Keep pure helpers extracted first; push IO/effects to edges.
- For Rust: prefer explicit `Result`, avoid silent `unwrap`/`expect` on persistence and inference paths, keep clippy `-D warnings` clean.
### 3. Gate after each batch
| Change kind | Minimum gate |
| ----------- | ------------ |
| Docs prose only | Spot-check claims vs the project's external-claims audit doc (abi: `docs/contracts/external-claims-audit.mdx`); run docs validator if structure changes |
| Tools scripts (no assertion rewrite) | Re-run the wired step or host gate |
| Public feature API | Update `mod.rs` + `stub.rs`; host gate |
| CLI/MCP handler | Contract suites + host gate (surface must stay frozen unless intentional) |
### 4. Cutover rules
- Do not delete the old path until parity is proven.
- Prefer expand → migrate callers → contract → delete.
- Leave the tree buildable and claim-honest mid-refactor.
## ABI-specific guardrails
- Source wins over prose (`AGENTS.md` / `CLAUDE.md` / `GEMINI.md` stay siblings when conventions change).
- Claims: no unproven sharding, production FHE, native GPU dispatch, non-loopback hardening, QPS/latency/accuracy figures.
- Live code is under `crates/*` (the Zig `src/` tree is retired). The substrate crates (`abi-foundation`, `abi-core`, `abi-telemetry`, `abi-compute`, `abi-wdbx`) come from sibling `../wdbx/crates/` as path deps: never vendor them or turn them into git deps.
- Keep `abi-ai`'s routing core store-agnostic; WDBX retrieval and persistence belong in the SEA/CLI/MCP layers.
- Split before a file crosses the size gate (`tools/check_rust_sizes.sh`: 1,000 lines per `.rs`, 200 for `crates/abi-cli/src/main.rs`).
- Prefer configurable temp dirs (`TMPDIR` / `SCRATCH` env) over hardcoded session paths in tools.
## Done criteria (before handoff)
- [ ] Chosen validation checklist (behavioral + modern + structural) checked
- [ ] Relevant gate log captured
- [ ] Active board (`tasks/todo.md`) updated if work was tracked
- [ ] No new unproven capability claims in docs
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |