big-file-refactor
Use when a source file has grown past roughly 1000 lines, when context compaction is losing track of a file's content, or when asked to break an oversized file into modules safely.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- big-file-refactor
- description
- Use when a source file has grown past roughly 1000 lines, when context compaction is losing track of a file's content, or when asked to break an oversized file into modules safely.
- disable-model-invocation
- true
03 SKILL.md 正文
Big-file refactor
Oversized files (>~800-1500 lines, language-dependent) rot agent context: reads get truncated, compaction loses content, edits hallucinate against what is no longer visible. This is the mechanical protocol for splitting one - never a rewrite.
Phase 0 - Gate
- A test suite must exist and be green BEFORE the first move. If coverage is thin, write characterization tests first (
edge-coverage,architecture's characterization-test pattern). No suite, no split. - Confirm the file is actually the problem: is it on the hot path of edits, or just big? Splitting cold files adds churn for nothing.
Phase A - Inventory
- List every top-level symbol (class, function, constant) with line ranges.
- Map dependents: who imports this file, and which symbols each importer uses (
grepfor each symbol). - Group symbols by cohesion: same data, same collaborator, same caller. These groups are the module candidates. A file that is one cohesive class is NOT a split candidate - extract methods or accept the size.
Phase B - Extraction
- One mechanical move at a time: cut a cohesion group into its target module, rewire imports, commit or checkpoint.
- Move code verbatim. Do NOT "improve" it while moving - renaming, reformatting, and logic edits belong to a separate pass after the split is green.
- Keep a compatibility shim (re-export from the old path) while external callers migrate; delete the shim only when no importer needs it.
- Target: leaf modules first (utilities, constants, types), then the groups with the fewest inbound edges.
Phase C - Verify
- Tests green after EVERY move, not at the end. A red move gets reverted, not patched forward.
- After the last move: no file should exceed the threshold, the old path either re-exports cleanly or is gone, and the import graph has no cycles.
- Sanity:
grepthe codebase for stale references to moved symbols.
Heuristics
- Threshold ~800-1000 lines for dense logic languages; generated/vendored/data files exempt.
- Prefer fewer, deeper modules over many shallow ones (
architecturedeep-module rule). - If a move fights you (symbols tangled, everything references everything), stop - the file needs redesign, not relocation. Say so.
Related
lean-codefor what to cut once modules are visible;de-slop/unslopfor the cleanup pass after structure settles;architecturefor seam design.
04 同仓库更多 Skills
montador-de-ideias
Use when assembling, expanding, or elevating a raw project idea or initial prompt into an ultra-detailed, first-principles dossier and compiled master prompt with journalistic OSINT market research, Tech Lead and Staff Architect justifications, atomic and modular hardening/optimization, and high-impact contact surfaces.
git-github-adaptive-engineering
Use when any task touches git history, GitHub issues/PRs/releases/CI, repo governance, or branch and merge decisions. Runs the Fase Zero situational-awareness battery, picks one of five delivery flows via the adaptive decision engine, and enforces commit/PR information-density standards. Orchestrates the gh, git-workflows, github-actions, pr, and debug/finish skills.
adaptive-agenda-calendar-routine-engine
Use when planning or executing work across hours, days, weeks, or sprints. Turns the calendar into a strict time-blocked agenda (HH:MM-HH:MM blocks carrying a routine profile, expected inputs, and a handoff output artifact), runs the 5-stage cognitive flow (Radar and Hunt -> Triage plus Steve Jobs conception -> workbench manifest -> >=32-cycle loop -> Close plus Open-Minded Scrum), and unfolds macro calendar milestones into micro agenda blocks through extensions/gcal/wrapper.py.
demo
Use when demonstrating a skill in a fixture project.
duplicate-skill
Use when testing duplicate skill name detection.
duplicate-skill
Use when testing duplicate skill name detection.