--- name: codebase-pattern-analyzer description: Analyze a reference codebase to discover and extract reusable architectural patterns. Produces structured pattern descriptions that can be turned into standalone skills. This is a meta-skill that bootstraps the skill evolution chain. --- # Codebase Pattern Analyzer Systematically analyze a reference codebase and extract reusable architectural patterns into structured descriptions. These descriptions become the raw material for new skills (via the `skill-template-generator` skill). ## When to Use - You need to understand how a large codebase is structured before replicating it - You want to extract a specific pattern (component architecture, service layer, API proxy, etc.) from a reference project - You are bootstrapping a new project that should follow the conventions of an existing one ## Step 1: Map the Directory Structure Read the top-level directory and identify the major code zones: ``` list_dir list_dir /src ``` Classify each directory into one of these roles: | Role | Typical Dirs | What to Look For | |------|-------------|------------------| | **Components** | `src/components/` | UI classes, base class inheritance, DOM manipulation | | **Services** | `src/services/` | Data fetching, API calls, circuit breakers, caching | | **Config** | `src/config/` | Constants, panel definitions, API endpoints, feature flags | | **Styles** | `src/styles/` | CSS custom properties, theme variables, grid layout | | **Utils** | `src/utils/` | Helper functions, formatting, DOM utilities | | **API Layer** | `api/`, `server/` | Serverless functions, route handlers, CORS, proxy logic | | **Entry Point** | `src/main.ts` | Bootstrap, panel instantiation, scheduler setup | ## Step 2: Identify the Component Pattern Find the base component class (usually the most imported file in `components/`): ``` read_file /src/components/Panel.ts ``` Extract these structural elements: 1. **Constructor options interface** — what config each component accepts (id, title, className, etc.) 2. **DOM structure** — how the element tree is built (header, content area, resize handles) 3. **Lifecycle methods** — constructor, destroy, show/hide, refresh 4. **State management** — loading/error/content states, fetching guards 5. **Data binding** — how data flows from service → render → DOM Record the pattern as: ``` COMPONENT PATTERN: Base class: [name] Options: [list of constructor params] DOM tree: [element hierarchy] States: [loading, error, content] Lifecycle: [init → fetch → render → destroy] Key methods: [getElement, showLoading, showError, setContent, refresh, destroy] ``` ## Step 3: Identify the Service Layer Pattern Examine 2-3 service files to find the common structure: ``` read_file /src/services/news.ts read_file /src/services/stock-market.ts ``` Look for: 1. **Circuit breaker / resilience** — retry logic, cooldown, cached fallback 2. **Interface definitions** — typed data shapes returned by each service 3. **Fetch pattern** — how HTTP calls are made (direct fetch, proxy, batching) 4. **Caching strategy** — TTLs, stale-while-revalidate, in-memory cache 5. **Error handling** — what happens on failure, default return values Record as: ``` SERVICE PATTERN: Resilience: [circuit breaker with N failures → cooldown] Cache: [in-memory, TTL=Xms] Fetch: [browser fetch → /api/... proxy → external API] Error: [catch → recordFailure → return default] Exports: [async functions, not class instances] ``` ## Step 4: Identify the API Proxy Pattern Read the server-side proxy layer: ``` list_dir /api/ read_file /api/_cors.js read_file /api/stocks.ts # or similar endpoint ``` Extract: 1. **File-per-endpoint structure** — one file per API domain 2. **CORS handling** — origin allowlist, preflight response 3. **API key isolation** — `process.env.*` usage, never exposed to frontend 4. **Cache headers** — `Cache-Control`, `s-maxage`, `stale-while-revalidate` 5. **Error wrapping** — structured JSON errors, never raw upstream responses 6. **Input validation** — query parameter checks before upstream call ## Step 5: Identify the Styling System ``` read_file /src/styles/main.css # first 100 lines for CSS variables ``` Extract: 1. **CSS custom properties** — color tokens, font stacks, spacing 2. **Theme structure** — dark/light mode switch mechanism 3. **Grid layout** — `grid-template-columns`, `auto-fill`, `minmax()` values 4. **Component styles** — panel base styles, header, content, scrollbar 5. **Semantic colors** — positive/negative, severity levels, status indicators 6. **Typography** — font family, sizes, letter-spacing, text-transform ## Step 6: Identify the Scheduling / Refresh Pattern ``` read_file /src/app/refresh-scheduler.ts ``` Extract: 1. **Registration API** — how panels register their refresh functions 2. **Interval management** — per-panel configurable intervals 3. **Visibility awareness** — pause when tab hidden, flush stale on return 4. **In-flight guards** — prevent duplicate concurrent refreshes 5. **Stagger logic** — avoid API burst when resuming ## Step 7: Synthesize Into Pattern Descriptions For each pattern discovered, produce a structured description: ```markdown ## Pattern: [Name] **Source file(s)**: [paths in reference codebase] **Category**: component | service | api | style | scheduler | utility ### Structure [Key structural elements — interfaces, classes, functions] ### Key Code [Minimal representative code snippet, 20-40 lines] ### Conventions [Naming, file organization, import paths] ### Dependencies [Other patterns this depends on] ### Adaptation Notes [What must change when applying to a different project] ``` ## Output The final output should be a list of pattern descriptions, one per architectural concern. These become the input to the `skill-template-generator` skill, which turns each pattern into a standalone SKILL.md. ## Tips - **Read broadly first, deeply second** — scan directory listings before reading individual files - **Follow imports** — if a component imports from `../services/`, read that service next - **Count instances** — if 10+ components extend the same base class, that's a core pattern - **Note what's NOT used** — no framework (React, Vue) means vanilla DOM; no ORM means raw fetch - **Compare 2-3 examples** of the same pattern to distinguish the template from the instance-specific parts

codebase-pattern-analyzer

Install this skill

Comments