Decomposition

Decomposition

You decompose a bloated file. This task has a wrong way that looks right: extracting aggressively into eight micro-files (navigation gets worse, nothing is comprehensible in isolation), cutting on textual seams (a random split at line 500 instead of at a real boundary), hiding the file behind a barrel index.ts that re-exports a still-bloated internal module, or splitting a function across files purely to drain line count. The right way is below. The core doctrine: extract at cognitive boundaries, not textual ones. A large screen is not "the top half" + "the bottom half"; it is a few hooks, one or more sub-components, a handful of pure helpers, and maybe a types module — each of which has a natural file.

To decompose a file over the ceiling

Step 0 — Verify there is work to do, and that it's allowed

First confirm the file exists and is actually over the ceiling. If it's under, refuse — there's nothing to do. Then check for an exemption and refuse politely, saying why, if the file is:

• Auto-generated — a *.gen.* file, a generated types file, or anything with an @generated / AUTOGENERATED header. Decomposition would just be undone on the next codegen.
• A snapshot (a __snapshots__/ file) — snapshots are atomic by definition.
• A test fixture of raw recorded data — it's tabular; line count is incidental.
• **A file where every extraction candidate is ` hook file → the project already uses hook extraction; follow that convention.
• An operations/ or helpers/ directory under a domain → pure-helper extraction is established; use that exact path.
• Sibling types.ts files → types get separated when they grow; replicate.
• Sub-component directories (e.g. a components/ folder beside a screen) → the JSX-extraction convention.

If the user puts pure helpers in one place, extract them there — mirror the existing convention, never impose a different one. The generic shapes to look for, adapted to whatever the project's stack and layout actually are:

• State-bearing logic (effects + refs + callbacks scoped to one concern) → a hook/module file.
• A large view subtree → its own component/view file.
• Pure transformation functions + their helpers → a helpers/operations module.
• A block of inline type definitions over ~50 LOC → a sibling types file.

Step 2 — Propose the split (do NOT edit yet)

Produce a plan in this shape and present it for approval:

File:  ( LOC)

Proposed split:
1.  →  (~)
2.  →  (~)
3.  →  (~)
4.  →  (~)

Resulting parent file: ~

Sanity-check before presenting:

• Each new file should land roughly 100–500 LOC. A chunk under ~30 LOC → fold it back, don't create a tiny file.
• The parent should retain only composition, the view root, and non-extractable wiring.
• Aim for 2–4 sibling files. Five-plus from one decomposition means either the original was 3000+ LOC (the user should break it down conceptually first) or you're over-extracting.
• If the parent would still sit above ~80% of the ceiling after every reasonable extraction, say so: this is two features, not one — propose splitting it conceptually rather than fighting for a tighter cut.

Step 3 — Get approval, then execute

The approval gate is structural, not optional — decomposition rewrites file structure and the user must see the plan before any code moves; skipping the handshake produces churn and resentment. After the user confirms or amends:

1. Create the new files one at a time, in this order — hooks / state-bearing logic first (most-coupled; extracting it first shrinks the parent's surface for everything after), view sub-components second (they pull cleanly once the hooks are out), pure helpers last (no closure dependencies, the easiest extraction). Reversing this — helpers first — leaves the stateful body untouched and barely drains the parent.
2. After each extraction, re-check the line count of the touched files.
3. After all extractions, run lint and tests on the touched files.
4. Verify the parent is now under the ceiling; iterate if not.

Skipping the post-extraction verification means broken imports and missing exports ship silently — it is not optional.

Step 4 — Don't game the rule

Refuse to suppress the size check with a disable comment, to wrap a still-bloated module behind a barrel re-export, or to split a function across files arbitrarily to dodge the count. If any of these feels like the only way to get under the ceiling, the honest answer is "this feature is two features" — split it conceptually.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vindm
• Source: vindm/dotclaude
• License: MIT
• Homepage: https://github.com/vindm/dotclaude

Install and usage instructions live in the source repository linked above.