Update to Matt Skills Curated

{
  "description": "Survey codebases for shallow modules, weak seams, and deepening opportunities, producing a visual report. Use when conducting architectural reviews, identifying design debt, finding deepening opportunities, or preparing codebase refactors — even if the user says \"analyze our architecture\". Do NOT use for basic syntax linting or formatting.",
  "included_files": [
    {
      "relative_path": "HTML-REPORT.md",
      "size_in_bytes": 6641
    },
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 123
    }
  ],
  "name": "improve-codebase-architecture",
  "skill_md_contents": "---\nname: improve-codebase-architecture\ndescription: \"Survey codebases for shallow modules, weak seams, and deepening opportunities, producing a visual report. Use when conducting architectural reviews, identifying design debt, finding deepening opportunities, or preparing codebase refactors — even if the user says \\\"analyze our architecture\\\". Do NOT use for basic syntax linting or formatting.\"\n---\n\n# Improve Codebase Architecture\n\nSurvey codebases for shallow modules, leaky abstractions, and weak seams, generating an interactive, visual HTML report in the OS temp directory with before/after architectural refactoring models.\n\n---\n\n## Core Invariants\n\n1. **YAGNI Scope First**: Prioritize hotspots in recent commit history (`git log --oneline`) where architectural friction is actively slowing development.\n2. **Strict Design Vocabulary**: Frame all findings using canonical terms (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and domain vocabulary from `CONTEXT.md`.\n3. **External Temp Report**: Write the visual report to the OS temporary directory (`<tmpdir>/architecture-review-<timestamp>.html`) with Tailwind CDN and Mermaid diagrams; never litter the repository with review HTML.\n4. **Before/After Visual Models**: Every deepening candidate must feature a clear before/after structural diagram illustrating interface simplification and implementation depth.\n5. **No Speculative Interface Proposing**: Propose candidate problem areas and deepening directions; do not propose concrete code interfaces until the user selects a candidate.\n\n---\n\n## Architecture & Map of Content (MOC)\n\n```\n[ Hotspot & Git Log Analysis ] ──► [ Deepening Candidate Survey ] ──► [ Generate HTML Report in /tmp ] ──► [ Grilling on Chosen Candidate ]\n```\n\n| Component | Responsibility | Reference |\n|---|---|---|\n| **Hotspot Scanner** | Identify frequently changed, high-friction files | Git log & subagent exploration |\n| **HTML Visual Report** | Render side-by-side Mermaid & Tailwind cards | `skills/improve-codebase-architecture/HTML-REPORT.md` |\n| **Candidate Deepening** | Socratic review of selected candidate | `skills/grilling/SKILL.md` + `skills/codebase-design/SKILL.md` |\n\n---\n\n## Step-by-Step Procedure (TWI)\n\n### Step 1: Scan Recent Codebase Hotspots\n- **Action**: Inspect `git log --oneline -n 100` and `CONTEXT.md` to identify high-churn modules and domain boundaries.\n- **Key Point**: Focus on modules where understanding one concept requires hopping between multiple fragmented files.\n- **Why**: Deepening stable, untouched legacy files yields low ROI compared to active hotspots.\n\n### Step 2: Survey Deepening Opportunities\n- **Action**: Evaluate candidate modules using the deletion test and locate shallow pass-throughs.\n- **Key Point**: Check for extracted pure functions that lack locality and leak callers' state.\n- **Inline Checklist**:\n  - [ ] Hotspot files identified from git churn\n  - [ ] 2–4 distinct deepening candidates formulated\n  - [ ] Candidates categorized by recommendation strength (`Strong`, `Worth exploring`, `Speculative`)\n\n### Step 3: Generate Self-Contained Visual HTML Report\n- **Action**: Write `<tmpdir>/architecture-review-<timestamp>.html` with Tailwind and Mermaid CDN scripts.\n- **Key Point**: Include problem descriptions, leverage/locality benefits, and side-by-side before/after Mermaid diagrams.\n- **Why**: Visual architecture diagrams communicate structural improvements far more effectively than walls of text.\n\n### Step 4: Open Report & Facilitate Candidate Selection\n- **Action**: Launch the HTML report via `open <path>` (macOS) / `xdg-open` (Linux) / `start` (Windows) and ask the user which candidate to explore.\n- **Key Point**: Upon selection, enter the grilling loop to settle module boundaries and update `CONTEXT.md` / ADRs.\n- **Why**: Collaborative candidate selection ensures team buy-in before investing in refactoring.\n\n---\n\n## Anti-Rationalization Guardrails\n\n| Tempting Rationalization | Binding Rule | Engineering Rationale |\n|---|---|---|\n| *\"Write the HTML review report directly into the repo root.\"* | **Write reports exclusively to the OS temp directory.** | Review artifacts should never pollute project Git history. |\n| *\"Draft full replacement code files immediately in the report.\"* | **Present architectural direction and diagrams first.** | Premature coding before agreeing on architectural seams leads to wasted effort. |\n| *\"Re-open settled ADR decisions without strong evidence.\"* | **Respect existing ADRs unless severe friction is demonstrated.** | Constant relitigation of settled decisions stalls progress. |\n\n"
}