# Suggested Split Policy
`rust-split` is a mechanical Rust source splitter. It does not decide when a
file must be split. This policy is the suggested rule for projects and agents
that want a default.
## Rule
- Around 1,000 LOC, perform a cohesion review.
- Do not split automatically just because a file reached 1,001 lines.
- If the file is still cohesive, document the reason and keep working.
- If a split is warranted, create responsibility owners below 500 LOC.
- Treat 500 LOC as a ceiling, not a packing target.
- Prefer cohesive smaller files over minimizing file count.
- Split earlier when a smaller file becomes a dumping ground for unrelated
concepts.
- Prefer planning ownership boundaries before implementation to avoid churn.
## How to Choose Boundaries
Split by responsibility, not by line count. Useful boundaries include:
- domain concept
- invariant
- lifecycle phase
- data owner
- dependency direction
- public API surface versus private implementation
- test support versus production behavior
Reference adjacency is useful evidence, but it is not architecture. Review the
generated grouping before applying it.
## How to Use rust-split with This Policy
1. Decide that a split is warranted using the project rule or this suggested
policy.
2. Run `rust-split explode <file> --out <fresh-dir>`.
3. Verify that the chunks in manifest order reproduce the original file byte for
byte.
4. Run `rust-split split <file> --max-loc 500 --out <fresh-output-dir>`.
5. Review grouping, module names, imports, re-exports, visibility changes,
comments, attributes, and conditional scopes before applying the output.
Section banners bound grouping, and local types with inherent impls stay in
the parent with private fields intact. Reference adjacency still determines
groups within sections. When these hints do not match the responsibilities
you chose, assemble the modules from the `explode` chunks instead (see
"Grouping rules and limits" in the skill). Retaining many shared types may
leave the parent over budget; the tool reports that rather than relocating
ownership arbitrarily.
Impl blocks with explicit owner-local members and retained types' local
lexical macro dependencies/consumers also stay in the parent, in source
order, to preserve visibility and macro redefinition semantics.
6. Let the compiler identify real import and visibility fallout.
7. Run the affected project's normal tests.
Keep formatting as a separate pass. A split should first be reviewable as a
relocation and module-wiring change.
## Incomplete splits and conditional modules
With the T1/T2 preservation fixes in 0.2.1, an item that cannot fit under the budget stays
intact in its original module, with its attributes, visibility and required
imports. This also applies inside recursively split modules. The command writes
this output for review, reports the remaining oversized items/files, and exits
non-zero when the budget is unmet, including root/module wiring overhead.
Do not treat that output as a completed split.
Inline modules with `cfg` or `cfg_attr` stay braced and inline in their original
module. Same-named platform implementations therefore keep separate bodies and
their original predicates. Large conditional modules require manual extraction;
this conservative behavior avoids generating a gate on a bare `mod name;`.
Existing conditional attributes on other declarations are not migrated by these
fixes; review those separately under the project's conditional-boundary rule.
Version 0.2.0 builds can omit oversized items or overwrite same-named conditional
module bodies even on exit 0. Use rust-split 0.2.1 or later.
## Exceptions
Some items are intentionally indivisible or belong near an existing boundary.
When an output file remains above the target, record why it is acceptable or what
later nested split should handle it.