Update to Matt Skills Curated

{
  "description": "Shared vocabulary and patterns for designing deep modules with narrow interfaces and clean seams. Use when designing module interfaces, finding deepening opportunities, deciding where seams go, or making code more testable and AI-navigable — even if the user says \"improve this module\". Do NOT use for whole-codebase architectural surveys.",
  "included_files": [
    {
      "relative_path": "DEEPENING.md",
      "size_in_bytes": 2553
    },
    {
      "relative_path": "DESIGN-IT-TWICE.md",
      "size_in_bytes": 2664
    },
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 102
    }
  ],
  "name": "codebase-design",
  "skill_md_contents": "---\nname: codebase-design\ndescription: \"Shared vocabulary and patterns for designing deep modules with narrow interfaces and clean seams. Use when designing module interfaces, finding deepening opportunities, deciding where seams go, or making code more testable and AI-navigable — even if the user says \\\"improve this module\\\". Do NOT use for whole-codebase architectural surveys.\"\n---\n\n# Codebase Design\n\nDesign deep, high-leverage modules that encapsulate complex domain behavior behind minimal interfaces placed at clear architectural seams.\n\n---\n\n## Core Invariants\n\n1. **Depth Over Surface Area**: Maximize internal implementation leverage while minimizing interface surface area (few methods, simple primitive parameters).\n2. **Interface as Test Surface**: External callers and unit tests cross the exact same seam; never pierce the interface to test internal private plumbing.\n3. **The Deletion Test**: If deleting a module causes complexity to vanish, it was an unnecessary pass-through; if complexity scatters across $N$ callers, it was earning its keep.\n4. **Real vs. Hypothetical Seams**: One adapter indicates a hypothetical seam; introduce an interface seam only when at least two concrete adapters vary across it.\n5. **Exact Design Vocabulary**: Strictly use canonical terminology (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**); avoid vague synonyms (service, component, boundary).\n\n---\n\n## Architecture & Map of Content (MOC)\n\n```\n┌───────────────────────────────────────┐\n│       Narrow Public Interface         │  ◄── Small surface (few methods, simple inputs)\n├───────────────────────────────────────┤\n│                                       │\n│          Deep Implementation          │  ◄── High leverage, hidden state, rich logic\n│                                       │\n└───────────────────────────────────────┘\n```\n\n| Component | Responsibility | Reference |\n|---|---|---|\n| **Module Deepening** | Refactor shallow pass-throughs into deep modules | `skills/codebase-design/DEEPENING.md` |\n| **Design It Twice** | Explore multi-model interface variations | `skills/codebase-design/DESIGN-IT-TWICE.md` |\n| **Testability Rules** | Accept dependencies, return pure values | Public seam tests |\n\n---\n\n## Step-by-Step Procedure (TWI)\n\n### Step 1: Evaluate Current Interface Depth & Seams\n- **Action**: Inspect the module's public methods, parameter signatures, and call sites.\n- **Key Point**: Check the ratio of interface cognitive overhead to internal capabilities.\n- **Why**: Shallow modules force callers to understand internal mechanics, destroying locality.\n\n### Step 2: Apply the Deletion Test & Simplify Signatures\n- **Action**: Consolidate fine-grained procedural methods into unified, intent-revealing operations.\n- **Key Point**: Hide internal state transformations and dependency instantiations behind the seam.\n- **Inline Checklist**:\n  - [ ] Methods reduced to minimal essential operations\n  - [ ] Dependencies passed in rather than created internally\n  - [ ] Functions return values rather than mutating global side effects\n\n### Step 3: Align Seam with Unit Test Harness\n- **Action**: Structure test suites to exercise the module strictly through its public interface.\n- **Key Point**: Eliminate internal mocking and testing of private helper functions.\n- **Why**: Testing through the interface ensures tests survive internal refactors without breakage.\n\n### Step 4: Explore Alternatives (Design It Twice)\n- **Action**: When designing complex or foundational modules, draft 2–3 radically different interface designs before coding.\n- **Key Point**: Compare candidates on depth, locality, and caller ergonomics.\n- **Why**: The first interface that comes to mind is rarely the deepest or most maintainable.\n\n---\n\n## Anti-Rationalization Guardrails\n\n| Tempting Rationalization | Binding Rule | Engineering Rationale |\n|---|---|---|\n| *\"Expose private helper functions so we can write unit tests for them.\"* | **Forbidden. Test exclusively through the public interface.** | Testing private helpers couples tests to implementation details and prevents refactoring. |\n| *\"Create an interface and adapter for a single implementation.\"* | **Wait for 2 adapters before extracting a generic seam.** | Speculative generalization creates shallow, unnecessary abstraction layers. |\n| *\"Break this 100-line cohesive function into 5 single-use files.\"* | **Maintain locality inside deep modules.** | Excessive fragmentation increases cognitive load and scatters related logic. |\n\n"
}