base

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 |
|-------|---------|--------|-----------|
| RED | `[test command]` | - | - |
| GREEN | `[test command]` | - | - |
| VALIDATE | `[lint && typecheck && test --coverage]` | - | - |
| COMPLETE | Moved to completed.md | - | - |

Todo Rules

1. Atomic - Each todo is a single, completable unit of work
2. Testable - Every todo has validation criteria and test cases
3. Sized - If larger than "M", break it down further
4. Independent - Minimize dependencies between todos
5. Tracked - Move between active.md → completed.md when done

Todo Execution Workflow (TDD - Mandatory)

Every todo MUST follow this exact workflow. No exceptions.

┌─────────────────────────────────────────────────────────────┐
│  1. RED: Write Tests First                                  │
│     └─ Create test file(s) based on Test Cases table        │
│     └─ Tests should cover all acceptance criteria           │
│     └─ Run tests → ALL MUST FAIL (proves tests are valid)   │
├─────────────────────────────────────────────────────────────┤
│  2. GREEN: Implement the Feature                            │
│     └─ Write minimum code to make tests pass                │
│     └─ Follow simplicity rules (20 lines/function, etc.)    │
│     └─ Run tests → ALL MUST PASS                            │
├─────────────────────────────────────────────────────────────┤
│  3. VALIDATE: Quality Gates                                 │
│     └─ Run linter (auto-fix if possible)                    │
│     └─ Run type checker (tsc/mypy/pyright)                  │
│     └─ Run full test suite with coverage                    │
│     └─ Verify coverage threshold (≥80%)                     │
├─────────────────────────────────────────────────────────────┤
│  4. COMPLETE: Mark Done                                     │
│     └─ Only after ALL validations pass                      │
│     └─ Move todo to completed.md                            │
│     └─ Checkpoint session state                             │
└─────────────────────────────────────────────────────────────┘

Execution Commands by Stack

Node.js/TypeScript:

# 1. RED - Run tests (expect failures)
npm test -- --grep "todo-description"

# 2. GREEN - Run tests (expect pass)
npm test -- --grep "todo-description"

# 3. VALIDATE - Full quality check
npm run lint && npm run typecheck && npm test -- --coverage

Python:

# 1. RED - Run tests (expect failures)
pytest -k "todo_description" -v

# 2. GREEN - Run tests (expect pass)
pytest -k "todo_description" -v

# 3. VALIDATE - Full quality check
ruff check . && mypy . && pytest --cov --cov-fail-under=80

React/Next.js:

# 1. RED - Run tests (expect failures)
npm test -- --testPathPattern="ComponentName"

# 2. GREEN - Run tests (expect pass)
npm test -- --testPathPattern="ComponentName"

# 3. VALIDATE - Full quality check
npm run lint && npm run typecheck && npm test -- --coverage --watchAll=false

Blocking Conditions

NEVER mark a todo as complete if:

• ❌ Tests were not written first (skipped RED phase)
• ❌ Tests did not fail initially (invalid tests)
• ❌ Any test is failing
• ❌ Linter has errors (warnings may be acceptable)
• ❌ Type checker has errors
• ❌ Coverage dropped below threshold

If blocked by failures:

## [TODO-042] - BLOCKED

**Blocking Reason:** [Lint error in X / Test failure in Y / Coverage at 75%]
**Action Required:** [Specific fix needed]

Bug Fix Workflow (TDD - Mandatory)

When a user reports a bug, NEVER jump to fixing it directly.

┌─────────────────────────────────────────────────────────────┐
│  1. DIAGNOSE: Identify the Test Gap                         │
│     └─ Run existing tests - do any fail?                    │
│     └─ If tests pass but bug exists → tests are incomplete  │
│     └─ Document: "Test gap: [what was missed]"              │
├─────────────────────────────────────────────────────────────┤
│  2. RED: Write a Failing Test for the Bug                   │
│     └─ Create test that reproduces the exact bug            │
│     └─ Test should FAIL with current code                   │
│     └─ This proves the test catches the bug                 │
├──────────────

---

*Content truncated.*