# Oss Refactor

> Apply careful structure and style hardening to a repository without unnecessary churn. Use when the user says "refactor for maintainability", "set up linting/formatting/types", "clean up this repo", or wants the minimum structural changes needed to make a project easier to maintain.

- Skill: `zeyuzhangzyz/oss-refactor` (Agent Skill)
- Install (CLI): `npx skillmds add zeyuzhangzyz/oss-refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zeyuzhangzyz/oss-refactor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zeyuzhangzyz (https://skillmd.com/u/zeyuzhangzyz)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/zeyuzhangzyz/oss-refactor

---


# OSS Refactor

Harden structure and style with the smallest credible set of changes. Preserve behavior, avoid vanity renames, and prefer extension of existing tooling over toolchain replacement.

## Context: $ARGUMENTS

## Input Contract

- Primary input: `OSS_PLAN.md` or a selected subset of plan items.
- Secondary input: current repo manifests and existing formatter/linter/type-check configuration.
- Default: if no explicit scope is given, work on the highest-priority refactor items from `OSS_PLAN.md`.

## Output Contract

Produce:

1. The requested code/config changes.
2. Minimal tooling configuration additions or updates.
3. `OSS_REFACTOR.md` summarizing:
   - selected scope
   - tooling choices and why
   - touched paths
   - commands run
   - rollback notes if any change should be reconsidered

The final summary in `OSS_REFACTOR.md` must include "Changed now" vs "Deferred intentionally".

## Non-goals

- Do not rename files, functions, or modules just for style consistency.
- Do not reformat the entire repository if only a few files changed.
- Do not introduce multiple new tools when one lightweight tool is enough.
- Do not alter public behavior unless the plan explicitly calls for it.

## Tool Selection Rules

Prefer existing repo choices first. If the repo has nothing yet, choose the lightest credible option:

- Python:
  - Format/lint: prefer `ruff format` + `ruff check`.
  - Type check: add `mypy` only if the repo already has meaningful annotations or the plan explicitly asks for it.
  - If no external deps are acceptable, document the recommendation and limit code changes to structure only.
- TypeScript:
  - Format: `prettier`.
  - Lint: `eslint`.
  - Type check: `tsc --noEmit`.
- JavaScript:
  - Reuse existing package scripts; avoid bolting on TypeScript just for hardening.
- Go:
  - `gofmt`, `go vet`, `go test`.
- Rust:
  - `cargo fmt --check`, `cargo clippy`, `cargo test`.
- Shell:
  - Prefer existing script style.
  - If no toolchain exists, use `bash -n` or `sh -n` validation before adding extra tools.

## Workflow

### Step 1: Confirm the minimum viable scope

- Read the relevant audit and plan items.
- Identify the exact files and boundaries touched by the refactor.
- If the request is vague, limit work to the smallest set that unlocks tests or CI.

### Step 2: Detect current toolchain

- Reuse existing manifests, scripts, config files, and editor conventions.
- Extend existing commands before inventing new top-level entry points.

### Step 3: Apply structural hardening

Examples of valid refactor targets:

- isolate side effects behind small functions
- split a monolithic script into one tiny reusable module plus a thin CLI
- centralize duplicated config/constants
- add explicit exit codes and error messages
- introduce a minimal formatter/linter config

Examples of invalid churn:

- wholesale file moves with no reliability gain
- blanket rename campaigns
- repo-wide style rewrites unrelated to changed code

### Step 4: Verify locally

- Run the narrowest relevant commands after every meaningful change.
- Prefer touched-file formatting/linting when possible.
- Record commands and outcomes in `OSS_REFACTOR.md`.

## Anti-patterns

- Do not modify files outside the planned change list.
- Do not do repo-wide formatting, rename sweeps, or directory churn unrelated to the selected scope.
- Do not add multiple new tools when one light tool or existing tooling is enough.
- Do not allow behavior changes to slip in under the label of "refactor".

## Self-check

Before declaring this stage complete, verify:

- [ ] `OSS_REFACTOR.md` exists and records selected scope, tooling choices, touched paths, commands run, and rollback notes if any.
- [ ] The artifact includes a `Changed now` section and a `Deferred intentionally` section.
- [ ] Any new tool or config added is explicitly justified in the artifact.
- [ ] Verification commands and outcomes are recorded after the final change set.

## Failure Handling

- If tooling installation is heavy or conflicts with the repo, stop after documenting the recommendation and keep code changes minimal.
- If a proposed refactor changes behavior, pause and either add tests first or roll back to the last safe structure.
- If hidden scope appears, update `OSS_REFACTOR.md` and hand control back to `/oss-plan` instead of expanding silently.

## Done Criteria

- `OSS_REFACTOR.md` exists and lists selected scope, tooling choices, touched paths, commands run, and rollback notes.
- The artifact includes a `Changed now` section and a `Deferred intentionally` section.
- All new tooling or config additions are minimal and explicitly justified.