codex-skills-library: Skill for Codex

Refactor Large File

Goal

Reduce complexity safely without changing public behavior or letting code files grow past 400 lines.

When to use

Use when a file is too large, mixes responsibilities, contains duplicated logic, exceeds 400 lines, or is difficult to test.

When not to use

Do not use for greenfield features unless the feature requires extracting existing behavior first.

Inputs

Inspect the large file, direct imports/exports, tests, public interfaces, and nearby modules with similar patterns.

Workflow

1. Identify existing responsibilities inside the file and note the current line count.
2. Mark public API boundaries that must not change.
3. If the file is at or above 400 lines, create a checkpoint before editing: copy the file to a backup path or save a patch diff that can be compared or restored later.
4. Extract cohesive units, not random line ranges.
5. Move related tests near the new owner when practical.
6. Preserve imports and behavior incrementally.
7. Run tests after each meaningful extraction.
8. If the refactor stalls, compare against the checkpoint before changing strategy.
9. Delete dead code once references are removed.
10. Document important ownership changes.

Extraction targets

Prefer named modules such as invoiceTotals, userPermissions, orderStatusPolicy, or useGalleryFilters instead of generic utils files.

Validation

Run tests for affected behavior after each meaningful extraction, then the repo's size validation and any typecheck, lint, or build checks if exports changed. If the file started over 400 lines, compare behavior against the checkpoint before declaring the refactor done.

Final response

Report extracted responsibilities, changed files, validation commands, and compatibility risks.