Skip to content
Skills Library
Programming · Building & coding

modularity

/modularity

This skill should be used when designing, planning, implementing, or reviewing any non-trivial change, or when the user asks to "split this file", "decouple X from Y", "refactor into modules" — enforces small, focused modules so any change fits in context without compaction

Licence
Apache-2.0
Last repository change
17.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

This skill should be used when designing, planning, implementing, or reviewing any non-trivial change, or when the user asks to "split this file", "decouple X from Y", "refactor into modules" — enforces small, focused modules so any change fits in context without compaction

Triggers from the description

split this filedecouple X from Yrefactor into modules
Original author description

This skill should be used when designing, planning, implementing, or reviewing any non-trivial change, or when the user asks to "split this file", "decouple X from Y", "refactor into modules" — enforces small, focused modules so any change fits in context without compaction

How it works

  1. The Rules
  2. Applying This Skill
  3. Splitting Strategies
  4. Anti-Patterns
  5. Rationalization Prevention
Original SKILL.md headings · 178 lines, 1,336 words
SKILL.md preview
---
name: modularity
title: "SB: Modularity"
description: This skill should be used when designing, planning, implementing, or reviewing any non-trivial change, or when the user asks to "split this file", "decouple X from Y", "refactor into modules" — enforces small, focused modules so any change fits in context without compaction
user-invocable: false
version: 0.1.0
---

# /modularity — Modular Design Enforcement

Every design, plan, and implementation MUST produce small, focused modules where any single change touches the fewest files possible and every touched file fits comfortably in context.

**Why this matters:** When files are large or tightly coupled, the active runtime must compact context to fit them — risking loss of key details. Modular design prevents this by keeping each unit small enough to reason about completely.

**When to invoke:** During PLANNING (after `/sb:context`, before `/sb:plan`) and during REVIEW (as part of code review criteria). This skill applies to both new code and modifications to existing code.

---

## The Rules

### Rule 1: File Size Limits

| File type | Soft limit | Hard limit | Action at hard limit |
|-----------|-----------|------------|---------------------|
| Source code (logic) | 150 lines | 300 lines | MUST split before proceeding |
| Test files | 200 lines | 400 lines | MUST split into focused test suites |
| Config / data | 100 lines | 200 lines | MUST split into per-concern configs |
| Documentation | 300 lines | 500 lines | MUST split into linked pages |

**Soft limit:** Refactor soon. Flag in code review.
**Hard limit:** Do not proceed. Split first, then continue.

Line counts exclude blank lines and comments. If a file approaches the soft limit during implementation, split it before the next commit — not "later."

### Rule 2: Single Responsibility Per File

Every file answers ONE question:
- "What does this file do?" must have a one-sentence answer.
- If the answer contains "and," the file does too much — split it.
- If two developers could work on different parts of the file simultaneously on unrelated tasks, it should be two files.

### Rule 3: Change Locality

Design so that any single feature, fix, or change touches **at most 3-5 files** (excluding tests). If a change requires touching more than 5 source files:
- STOP. The design has a coupling problem.
- Identify which files are changing for the same reason — they should share an abstraction.
- Identify which files are changing for different reasons — they need a cleaner interface between them.

### Rule 4: Interface-First Design

Before writing any implementation:
1. Define the module's **public interface** — what it exposes to consumers.
2. Define its **dependencies** — what it imports/requires.
3. The interface should be understandable without reading the implementation.
4. Consumers should never need to know implementation details.

If you can't define the interface in <10 lines, the module is too complex — decompose further.

### Rule 5: Context-Window-Aware Decomposition

When designing a system, apply this test to every module:

> "Can the active runtime read this file, its tests, and the files it directly depends on — all at once — without exceeding context or needing to compact?"

If no: the module is too large or has too many dependencies. Decompose until the answer is yes.

**Practical guideline:** Any single task (implement, fix, review) should require reading **at most 5-7 files totaling under 1500 lines**. Design the system to make this true.

### Rule 6: Dependency Direction

- Dependencies flow ONE direction (no circular imports).
- High-level modules depend on abstractions, not low-level details.
- If module A imports module B and module B imports module A, extract the shared concern into module C.

### Rule 7: Co-location

Files that change together live together. Organize by **feature/domain**, not by **technical layer**.

```
WRONG (layer-based):
  controllers/user.ts
  controllers/order.ts
  services/user.ts
  services/order.ts
  models/user.ts
  models/order.ts

RIGHT (feature-based):
  user/controller.ts
  user/service.ts
  user/model.ts
  order/controller.ts
  order/service.ts
  order/model.ts
```

When a change to "users" only touches files in `user/`, modularity is working.

---

## Applying This Skill

### During Planning (/sb:context -> /sb:plan)

Before finalizing any design or plan, run the **Modularity Checklist**:

- [ ] Every planned file has a one-sentence responsibility
- [ ] No planned file exceeds the soft line limit for its type
- [ ] The file structure is organized by feature/domain, not layer
- [ ] Any single task in the plan touches at most 3-5 source files
- [ ] Every module's public interface is defined before its implementation
- [ ] Dependencies flow in one direction — no circular imports
- [ ] The context test passes: any task requires reading <1500 lines total

If any item fails: **redesign before proceeding to implementation.** Do not defer modularity to refactoring — it is far cheaper to decompose correctly upfront.

### During Implementation (/sb:execute)

As you write code:
- Check file size after each commit. If approaching the soft limit, split NOW.
- If a function grows beyond 30 lines, extract sub-functions or a helper module.
- If you're adding a new feature and touching >5 files, stop and ask: "Is there a missing abstraction?"

### During Review (sb:review / sb:review-triage)

Verify these as part of every code review:
- No file exceeds the hard limit
- Each file's responsibility is clear and singular
- Change locality: the PR touches a reasonable number of files
- No circular dependencies introduced
- New modules have well-defined interfaces

**Adversarial mode rule: No future credit.** When reviewing, reject any reasoning that defers a current violation to a future action (backlog item, next phase, open issue). The review grades the code as it exists now. A planned fix is not a fix; a GitHub issue is not code. If a file violates the limits today, the review outcome is ❌ Fail — regardless of intent, roadmap, or tracking.

### When Modifying Existing Code

If existing code violates these rules:
- Not required to fix violations in unrelated files.
- Required: do not make violations worse.
- If the file being modified already exceeds the hard limit, include a split as part of the change.
- If the change would push a file past the soft limit, split first.

---

## Splitting Strategies

When a file needs to be split, use these patterns:

**By sub-feature:** `auth.ts` → `auth/login.ts`, `auth/register.ts`, `auth/token.ts`

**By abstraction level:** `api.ts` → `api/routes.ts`, `api/middleware.ts`, `api/validation.ts`

**By data type:** `utils.ts` → `string-utils.ts`, `date-utils.ts`, `array-utils.ts`

**Extract shared logic:** If two files share helper functions, extract to a shared module rather than duplicating.

---

## Anti-Patterns

| Pattern | Problem | Fix |
|---------|---------|-----|
| "God file" — one file does everything | Impossible to change safely | Split by responsibility |
| "Shotgun surgery" — one change touches 10+ files | Missing abstraction | Extract shared concern |
| "Barrel files" re-exporting everything | Hides dependency structure | Import directly from source |
| Premature abstraction for one use case | Unnecessary complexity | Three similar blocks > one premature abstraction |
| Layer-based organization | Unrelated files change together | Reorganize by feature |
| "Utils" or "helpers" grab-bag | No clear responsibility | Split by domain or delete |

---

## Rationalization Prevention

| Excuse | Reality |
|--------|---------|
| "It's just one more function" | That's how 800-line files happen. Split now. |
| "Splitting will create too many files" | Many small files > few large files. Always. |
| "I'll refactor later" | You won't. The soft limit exists to prevent this. |
| "This file is the natural home for this" | If it exceeds the limit, it's not. Find a better home. |
| "It's all related" | Related is not the same as same-responsibility. |
| "The framework forces this structure" | Most frameworks work fine with smaller modules. Check. |
| "It's tracked in the backlog / GitHub issue #N" | A planned fix is not a fix. The violation exists now. ❌ Fail. Fix it or accept the block. |
| "The current milestone plan addresses this" | Planning intent ≠ code compliance. The gate evaluates actual structure, not intent. ❌ Fail until the code is changed. |
| "We'll fix this in the next phase / sprint" | Future tense is not present tense. Rate the current state. ❌ Fail if the rule is violated today. |

Versions

The database has no other skills named modularity.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 59801327cb7b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100reusability
    This skill should be used when designing, planning, implementing, or reviewing any non-trivial change, or when the user asks to "generalize this", "extract shared util", "deduplicate this" — enforces DRY, well-defined abstractions, and composable components so code is written…
  • 86plan-before-code
    Decide the shape and the size of a change before writing it. Use for any non-trivial edit, a new mechanism, a refactor, or work whose scope is not obvious from the request.
  • 100eng-change-checklist
    Short checklist of engineering principles to apply before and after non-trivial work. Use when planning or reviewing a non-trivial change, debugging a stubborn failure, designing types or boundaries, or deciding how to sequence a migration.
  • 100abp-modularity
    ABP Framework v10.x (10.4–10.6) modularity: AbpModule, [DependsOn], module lifecycle, plugin modules, modular monolith. Use when creating a module, defining module dependencies, or building a modular architecture in ABP.
  • 100abp-modularity
    ABP Framework v10.x (10.4–10.6) modularity: AbpModule, [DependsOn], module lifecycle, plugin modules, modular monolith. Use when creating a module, defining module dependencies, or building a modular architecture in ABP.
  • 90design-deep-modules
    Judge interface depth — deep modules hide complexity behind small interfaces. Use when designing a module/API, reviewing a class boundary, or reducing complexity.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.