/base

name: base
description: Universal coding patterns, constraints, TDD workflow, atomic todos
when-to-use: Always loaded as foundation for all projects - TDD workflow, simplicity rules, atomic todos
user-invocable: false
effort: medium

Base Skill - Universal Patterns

Core Principle

Complexity is the enemy. Every line of code is a liability. The goal is software simple enough that any engineer (or AI) can understand the entire system in one session.

---

Simplicity Rules

These limits apply to every file created or modified.

Function Level

• **Maximum 20 lines per function** - if longer, decompose IMMEDIATELY
• **Maximum 3 parameters per function** - if more, use an options object or decompose
• **Maximum 2 levels of nesting** - flatten with early returns or extract functions
• **Single responsibility** - each function does exactly one thing
• **Descriptive names over comments** - if you need a comment to explain what, rename it

File Level

• **Maximum 200 lines per file** - if longer, split by responsibility BEFORE continuing
• **Maximum 10 functions per file** - keeps cognitive load manageable
• **One export focus per file** - a file should have one primary purpose

Module Level

• **Maximum 3 levels of directory nesting** - flat is better than nested
• **Clear boundaries** - each module has a single public interface
• **No circular dependencies** - ever

Enforcement Protocol

**Before completing ANY file:** 1. Count total lines - if > 200, STOP and split 2. Count functions - if > 10, STOP and split 3. Check each function length - if any > 20 lines, STOP and decompose 4. Check parameter counts - if any > 3, STOP and refactor

**If limits are exceeded during development:**

⚠️ FILE SIZE VIOLATION DETECTED

[filename] has [X] lines (limit: 200)

Splitting into:
- [filename-a].ts - [responsibility A]
- [filename-b].ts - [responsibility B]

**Never defer refactoring.** Fix violations immediately, not "later".

---

Architectural Patterns

Functional Core, Imperative Shell

• Pure functions for business logic - no side effects, deterministic
• Side effects only at boundaries - API calls, database, file system at edges
• Data in, data out - functions transform data, they don't mutate state

Composition Over Inheritance

• No inheritance deeper than 1 level - prefer interfaces/composition
• Small, composable utilities - build complex from simple
• Dependency injection - pass dependencies, don't import them directly

Error Handling

• Fail fast, fail loud - errors surface immediately
• No silent failures - every error is logged or thrown
• Design APIs where misuse is impossible

---

Testing Philosophy

• **100% coverage on business logic** - the functional core
• **Integration tests for boundaries** - API endpoints, database operations
• **No untested code merges** - CI blocks without passing tests
• **Test behavior, not implementation** - tests survive refactoring
• **Each test runs in isolation** - no interdependence

---

Anti-Patterns (Never Do This)

• ❌ Global state
• ❌ Magic numbers/strings - use named constants
• ❌ Deep nesting - flatten or extract
• ❌ Long parameter lists - use objects
• ❌ Comments explaining "what" - code should be self-documenting
• ❌ Dead code - delete it, git remembers
• ❌ Copy-paste duplication - extract to shared function
• ❌ God objects/files - split by responsibility
• ❌ Circular dependencies
• ❌ Premature optimization
• ❌ Large PRs - small, focused changes only
• ❌ Mixing refactoring with features - separate commits

---

Documentation Structure

Every project must have clear separation between code docs and project specs:

project/
├── docs/                      # Code documentation
│   ├── architecture.md        # System design decisions
│   ├── api.md                 # API reference (if applicable)
│   └── setup.md               # Development setup guide
├── _project_specs/            # Project specifications
│   ├── overview.md            # Project vision and goals
│   ├── features/              # Feature specifications
│   │   ├── feature-a.md
│   │   └── feature-b.md
│   ├── todos/                 # Atomic todos tracking
│   │   ├── active.md          # Current sprint/focus
│   │   ├── backlog.md         # Future work
│   │   └── completed.md       # Done items (for reference)
│   ├── session/               # Session state (see session-management.md)
│   │   ├── current-state.md   # Live session state
│   │   ├── decisions.md       # Key decisions log
│   │   ├── code-landmarks.md  # Important code locations
│   │   └── archive/           # Past session summaries
│   └── prompts/               # LLM prompt specifications (if AI-first)
└── CLAUDE.md                  # Claude instructions (references skills)

What Goes Where

| Location | Content | |----------|---------| | `docs/` | Technical documentation, API refs, setup guides | | `_project_specs/` | Business logic, features, requirements, todos | | `_project_specs/session/` | Session state, decisions, context for resumability | | `CLAUDE.md` | Claude-specific instructions and skill references |

---

Atomic Todos

All work is tracked as atomic todos with validation and test criteria.

Todo Format (Required)

## [TODO-001] Short descriptive title

**Status:** pending | in-progress | blocked | done
**Priority:** high | medium | low
**Estimate:** XS | S | M | L | XL

### Description
One paragraph describing what needs to be done.

### Acceptance Criteria
- [ ] Criterion 1 - specific, measurable
- [ ] Criterion 2 - specific, measurable

### Validation
How to verify this is complete:
- Manual: [steps to manually test]
- Automated: [test file/command that validates this]

### Test Cases
| Input | Expected Output | Notes |
|-------|-----------------|-------|
| ... | ... | ... |

### Dependencies
- Depends on: [TODO-xxx] (if any)
- Blocks: [TODO-yyy] (if any)

### TDD Execution Log
| Phase | Command | Result | Timestamp