# Kiss Modularity

> KISS — Modularity

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

---


# KISS — Modularity

Keep units bite-size and cohesive so a human — and the map — can navigate them. There are **two**
ways to fail here, not one: a file that grows into a monolith, and a codebase that shatters into so
many tiny files that the tree and the index become their own complexity. Modularity means steering
between both. Splitting is not automatically good; over-splitting is its own mess.

## One coherent concern per *unit* — and a unit is a section OR a file

The rule is **one coherent concern per unit**, not "one function per file." A concern can be large.
Modularity works at two levels:

- **Section** — a banner-labeled block inside a file (see `kiss-readable`): bounded, liftable, and
  indexed by the map. Modularity *without* a new file.
- **File** — a whole module.

**Reach for a section before a new file.** A section gives every benefit of a split — a named,
bounded, mappable, transplantable unit — at none of the cost: no extra file in the tree, no extra
thing to wire, no bigger map. Promote a section to its own file only when it **earns** it:

1. the file is genuinely **too big** (size tiers below), or
2. it holds genuinely **independent concerns** that change for different reasons, or
3. another module needs to **reuse** that section on its own.

If none of those is true, keep it a section. A file that exists only to hold one trivial thing used
in one place is **fragmentation, not modularity** — fold it back in.

## The two failure modes

| Failure | Looks like | Fix |
|---|---|---|
| **Monolith** | one file doing several things; 800+ lines | split a concern out (section → file) |
| **Fragmentation** | many 10–30 line files; ten files to follow one flow; a sprawling map | consolidate trivial files into sections of a cohesive module |

Minimize file count **subject to clarity**: the fewest files that each hold one clear concern — not
the most units you can manufacture.

## Size tiers (the too-big cliff; defaults — tune per repo)

| Lines | Tier | Action |
|---|---|---|
| ~300 | review | Pause: does this still have one coherent concern? |
| ~500 | extract | Pull a section out *before* adding more. |
| ~800 | hard stop | Do not add; split first. |

The tiers (a review point, an extract-first point, a line you don't cross) matter more than the
exact numbers.

## Bloat vs. legitimate length

Length is a proxy. A long file that does **one** thing and is cleanly **sectioned** is legitimate —
don't split it for the line count alone. A short file that tangles three concerns is the real
problem, even under budget. Size flags candidates; cohesion arbitrates.

## Responsibility check — before every edit

State the file's single concern in one sentence before editing. Can't? It's doing too much. But
before you split into a new *file*, ask whether a *section* would do — usually it will.

## Common mistakes

- **Over-splitting** — a file per function. Sections are cheaper, and the map stays smaller.
- **Splitting for line count alone** — size is a proxy, not the disease; mixed concerns are.
- **Keeping a one-function file used in one place** — fold it into its caller's module as a section.
- **Reading "one responsibility per file" as a mandate to atomize** — it means one *concern* per
  *unit*, and a section is a unit.