feat: Add typed-holes-refactor skill for systematic TDD refactoring

Add comprehensive typed-holes-refactor skill for systematic codebase refactoring using Design by Typed Holes methodology:

- New skill directory: skills/typed-holes-refactor/
  - SKILL.md: Main documentation (~350 lines) with workflows and principles
  - README.md: Overview and quick start guide (~197 lines)
  - references/: Comprehensive pattern catalogs
    - HOLE_TYPES.md: Complete taxonomy of refactoring holes
    - CONSTRAINT_RULES.md: Constraint propagation patterns
    - VALIDATION_PATTERNS.md: Test patterns for validation
  - scripts/: Python automation tools (~3000 total lines)
    - discover_holes.py: Analyze codebase and generate REFACTOR_IR.md
    - next_hole.py: Show next resolvable holes based on dependencies
    - validate_resolution.py: Check if hole resolution satisfies constraints
    - propagate.py: Update dependent holes after resolution
    - generate_report.py: Create comprehensive delta report

- Updated skills/_INDEX.md:
  - Added to "Workflow & Task Management" category (5 → 6 skills)
  - Added to discovery patterns by technology/task/domain
  - Added "Systematic Codebase Refactoring" workflow example
  - Added to quick reference table
  - Updated total skills count: 133 → 134
  - Updated last modified date: 2025-10-23

- Updated CLAUDE.md:
  - Added typed-holes-refactor to skills catalog (133 → 134 total)
  - Updated "Workflow & Tasks" category (5 → 6 skills)
  - Added to quick category reference
  - Updated quality standards count

Key features:
- Test-driven refactoring: Write validation tests BEFORE implementing
- Safe by construction: Works in branches, preserves main and .beads/
- Systematic hole resolution with dependency tracking
- Continuous validation against characterization tests
- Comprehensive tooling for discovery, validation, and reporting
- Formal completeness gates ensure refactoring quality

Use when: Architecture refactoring, code consolidation, technical debt reduction, complexity reduction, or quality improvement projects requiring systematic, validated changes.

Author: rand

CLAUDE.md

@@ -494,7 +494,7 @@ open https://ui.shadcn.com/themes
 **New approach**: Atomic, composable skills (~300 lines avg, <500 line guideline)
 
 ### Quality Standards (as of 2025-10-23)
-- ✅ **133 skills** with YAML frontmatter (agent_skills_spec.md compliant)
+- ✅ **134 skills** with YAML frontmatter (agent_skills_spec.md compliant)
 - ✅ **0 future dates** - all dates validated by CI
 - ✅ **Automated testing** - code syntax validation in CI
 - 🔄 **Size optimization** - 89 skills >500 lines identified for splitting
@@ -531,15 +531,15 @@ Read zig-memory-management.md, zig-testing-patterns.md
 Read beads-workflow.md + beads-context-strategies.md + beads-multi-session-patterns.md
 ```
 
-### Skills Catalog (133 Total)
+### Skills Catalog (134 Total)
 
-**Core Categories** (75 skills):
+**Core Categories** (76 skills):
 - **API Design** (7): REST, GraphQL, auth/authz, rate limiting, versioning, error handling
 - **Testing** (6): Unit, integration, e2e, TDD, coverage, performance testing
 - **Containers** (5): Dockerfile optimization, Compose, security, networking, registries
 - **Frontend** (8): React patterns, Next.js App Router, state/data/forms, a11y, performance, SEO
 - **Database** (11): Postgres (optimization, migrations, schema), MongoDB, Redis, Redpanda/Kafka streaming, Apache Iceberg, DuckDB analytics, pooling, ORMs, selection
-- **Workflow & Tasks** (5): Beads workflow, context strategies, multi-session, dependency management
+- **Workflow & Tasks** (6): Beads workflow, context strategies, multi-session, dependency management, typed-holes refactoring
 - **Quality & Content Review** (1): Anti-slop detection and cleanup (text, code, design)
 - **Meta Skills** (4): Skill discovery and planning for repositories and prompts
   - Discovery: `skill-repo-discovery.md` (analyze repos), `skill-prompt-discovery.md` (analyze prompts)
@@ -578,7 +578,7 @@ Frontend:       react-*.md (5) | nextjs-*.md (2) | web-*.md, frontend-*.md (3)
 DevOps/Infra:   cicd/ (5) | infrastructure/ (6) | observability/ (5)
 Data:           data/ (5) | realtime/ (4)
 Specialized:    modal-*.md (8) | swiftui-*.md, swift-*.md, ios-*.md (6) | zig-*.md (6)
-Workflow:       beads-*.md (4) | tui-*.md (5) | network-*.md (5)
+Workflow:       beads-*.md (4) | typed-holes-refactor/ (1 skill + 3 refs + 5 scripts) | tui-*.md (5) | network-*.md (5)
 Quality:        anti-slop/ (1 skill + 3 reference guides + 2 scripts)
 Meta:           skill-*.md (5 including skill-creation.md)
 Formal:         formal/z3-*.md, formal/sat-*.md, formal/smt-*.md (3) | formal/lean-*.md (4) | formal/csp-*.md (3)
@@ -603,7 +603,7 @@ Mobile:         mobile/react-native-*.md (4)
 4. **Deep dive?** Search `skills/_INDEX.md` by technology/task/problem domain
 5. **Emergency?** Read relevant skill directly: `skills/api-*.md`, `skills/cicd/*.md`
 
-**Full catalog**: `skills/_INDEX.md` (133 skills, workflows, search patterns, combinations)
+**Full catalog**: `skills/_INDEX.md` (134 skills, workflows, search patterns, combinations)
 
 ### Skill Quality Assurance
 All skills now include:

skills/_INDEX.md

@@ -110,19 +110,21 @@ This index catalogs all atomic skills available in the skills system, organized
 
 ---
 
-### Workflow & Task Management (5 skills)
+### Workflow & Task Management (6 skills)
 
 | Skill | Use When | Lines |
 |-------|----------|-------|
 | `beads-workflow.md` | Starting sessions, running bd commands, managing issue workflow | ~350 |
 | `beads-dependency-management.md` | Creating issue relationships, managing blockers, organizing work hierarchies | ~450 |
 | `beads-context-strategies.md` | Managing Claude context, preventing bloat, preserving workflow state | ~400 |
 | `beads-multi-session-patterns.md` | Complex multi-session tasks, long-horizon work chains, parallel streams | ~350 |
+| `typed-holes-refactor/SKILL.md` | Systematic codebase refactoring using Design by Typed Holes - iterative, test-driven with formal validation | ~350 |
 | `skill-creation.md` | Creating new atomic skills, maintaining skills system, CLAUDE.md integration | ~400 |
 
 **Common workflows:**
 - New session: `beads-workflow.md` → `beads-context-strategies.md`
 - Complex task: `beads-workflow.md` → `beads-dependency-management.md` → `beads-multi-session-patterns.md`
+- Systematic refactoring: `typed-holes-refactor/SKILL.md` → Test-driven hole resolution → Constraint propagation
 - Context management: `beads-context-strategies.md` (throughout session)
 - Create new skill: `skill-creation.md` → Update _INDEX.md → Update CLAUDE.md
 
@@ -508,6 +510,7 @@ This index catalogs all atomic skills available in the skills system, organized
 **TUI (Rust):** Search `ratatui-*.md`, `tui-*.md`
 **Zig:** Search `zig-*.md`
 **Beads:** Search `beads-*.md`
+**Refactoring:** `typed-holes-refactor/SKILL.md` (systematic TDD refactoring)
 **Quality & Content:** `anti-slop/SKILL.md`, `anti-slop/references/*.md`
 **Meta Skills:** Search `skill-*.md`
 **CI/CD:** Search `cicd/*.md`, `github-*.md`, `ci-*.md`, `cd-*.md`
@@ -554,6 +557,12 @@ This index catalogs all atomic skills available in the skills system, organized
 - Code patterns: `anti-slop/references/code-patterns.md`
 - Design patterns: `anti-slop/references/design-patterns.md`
 
+**Refactoring:**
+- Systematic refactoring: `typed-holes-refactor/SKILL.md`
+- Hole discovery: `typed-holes-refactor/scripts/discover_holes.py`
+- Constraint propagation: `typed-holes-refactor/references/CONSTRAINT_RULES.md`
+- Validation patterns: `typed-holes-refactor/references/VALIDATION_PATTERNS.md`
+
 **Networking:**
 - iOS: `ios-networking.md`
 - Secure: `mtls-implementation.md`, `tailscale-vpn.md`
@@ -598,6 +607,7 @@ This index catalogs all atomic skills available in the skills system, organized
 **DevOps/SRE:** `cicd/*.md`, `infrastructure/*.md`, `observability/*.md`, `cost-optimization.md`, `heroku-*.md`, `netlify-*.md`
 **Data Engineering:** `data/*.md`, `stream-processing.md`, `batch-processing.md`, `data-validation.md`
 **Content Quality:** `anti-slop/SKILL.md` (text, code, design quality review and cleanup)
+**Refactoring:** `typed-holes-refactor/SKILL.md` (systematic test-driven refactoring with hole resolution)
 **Real-time Systems:** `realtime/*.md`, `websocket-implementation.md`, `server-sent-events.md`, `pubsub-patterns.md`
 **Formal Methods:** `formal/z3-*.md`, `formal/lean-*.md`, `formal/sat-*.md`, `formal/smt-*.md`, `formal/csp-*.md`
 **Machine Learning:** `ml/unsloth-*.md`, `ml/diffusion-*.md`, `ml/llm-*.md`, `ml/stable-diffusion-*.md`
@@ -702,6 +712,14 @@ This index catalogs all atomic skills available in the skills system, organized
 3. `beads-multi-session-patterns.md` - Long-horizon patterns
 4. `beads-context-strategies.md` - Context preservation (throughout)
 
+### Systematic Codebase Refactoring
+1. `typed-holes-refactor/SKILL.md` - Design by Typed Holes methodology
+2. Create characterization tests - Capture current behavior
+3. Discover holes - Identify architectural unknowns
+4. Resolve holes iteratively - Test-driven development
+5. Propagate constraints - Update dependent holes
+6. Generate report - Comprehensive delta analysis
+
 ### SAT/SMT-based Verification
 1. `z3-solver-basics.md` - Z3 fundamentals
 2. `sat-solving-strategies.md` - SAT encoding
@@ -823,24 +841,25 @@ This index catalogs all atomic skills available in the skills system, organized
 | Review content for AI slop | anti-slop/SKILL.md | 1 |
 | Clean up generic code | anti-slop/references/code-patterns.md | 1 |
 | Review design quality | anti-slop/references/design-patterns.md | 1 |
+| Refactor codebase systematically | typed-holes-refactor/SKILL.md | 1 |
 
 ---
 
 ## Total Skills Count
 
-- **133 atomic skills** across 28 categories
+- **134 atomic skills** across 28 categories
 - **Average 310 lines** per skill
 - **100% focused** - each skill has single clear purpose
 - **Cross-referenced** - related skills linked for discoverability
 
 ### By Category Breakdown
-**Core Foundation** (75 skills):
+**Core Foundation** (76 skills):
 - API Design: 7 skills
 - Testing: 6 skills
 - Containers: 5 skills
 - Frontend: 8 skills
 - Database: 11 skills
-- Workflow & Task Management: 5 skills
+- Workflow & Task Management: 6 skills (including typed-holes refactoring)
 - Quality & Content Review: 1 skill (anti-slop detection and cleanup)
 - Meta Skills: 4 skills (skill discovery and planning)
 - iOS/Swift: 6 skills
@@ -888,5 +907,5 @@ See `MIGRATION_GUIDE.md` for detailed mapping.
 ---
 
 **Last Updated:** 2025-10-23
-**Total Skills:** 133
+**Total Skills:** 134
 **Format Version:** 1.0 (Atomic)

skills/typed-holes-refactor/README.md

@@ -0,0 +1,196 @@
+# Typed Holes Refactor - Claude Code Skill
+
+A comprehensive skill for systematically refactoring codebases using the Design by Typed Holes methodology - iterative, test-driven refactoring with formal hole resolution, constraint propagation, and continuous validation.
+
+## What This Skill Does
+
+This skill helps you refactor codebases by:
+
+1. **Discovering architectural unknowns** ("holes") in your codebase
+2. **Resolving holes systematically** using test-driven development
+3. **Propagating constraints** through dependency graphs
+4. **Validating continuously** to prevent regressions
+5. **Generating comprehensive reports** comparing old vs new
+
+## Key Features
+
+- ✅ **Test-Driven**: Write validation tests BEFORE refactoring
+- ✅ **Safe**: Works in branches, preserves main and .beads/
+- ✅ **Systematic**: Formal hole resolution with dependency tracking
+- ✅ **Validated**: Continuous validation against characterization tests
+- ✅ **Comprehensive**: Complete tooling for discovery, validation, and reporting
+
+## Installation
+
+### Option 1: Claude Desktop/Web (Recommended)
+
+1. Download `typed-holes-refactor.skill`
+2. In Claude, go to Settings → Skills
+3. Click "Add Skill" and upload the .skill file
+4. The skill is now available for use!
+
+### Option 2: Manual Installation (Claude Code)
+
+```bash
+# Copy skill to your skills directory
+mkdir -p ~/.claude/skills
+unzip typed-holes-refactor.skill -d ~/.claude/skills/
+```
+
+## Quick Start
+
+### Step 1: Install the Skill
+
+Follow installation instructions above.
+
+### Step 2: Start Claude Code in Your Project
+
+```bash
+cd your-project
+claude-code
+```
+
+### Step 3: Use the Initial Prompt
+
+Copy and paste this into Claude Code:
+
+```
+I want to refactor this codebase using the typed-holes-refactor skill. Here's the context:
+
+Repository: [describe your repo]
+Goal: [what you want to achieve]
+Constraints: [any specific constraints]
+
+Please:
+1. Read the typed-holes-refactor skill
+2. Create a safe refactor branch
+3. Run discover_holes.py to analyze the codebase
+4. Create baseline characterization tests
+5. Help me resolve holes one by one using test-driven development
+
+Let's start with the discovery phase.
+```
+
+### Step 4: Follow the Process
+
+The skill will guide you through:
+
+1. **Discovery**: Analyze codebase and identify holes
+2. **Characterization**: Write tests capturing current behavior
+3. **Resolution**: Resolve holes one by one with TDD
+4. **Validation**: Continuous validation at each step
+5. **Reporting**: Generate comprehensive delta report
+
+## Workflow Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. DISCOVERY                                             │
+│    git checkout -b refactor/typed-holes-v1              │
+│    python scripts/discover_holes.py                      │
+│    → Creates REFACTOR_IR.md with hole catalog           │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 2. CHARACTERIZATION                                      │
+│    Create tests/characterization/test_*.py              │
+│    → Captures exact current behavior                     │
+│    → Safety net for refactoring                          │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 3. ITERATIVE RESOLUTION (repeat for each hole)          │
+│    a. python scripts/next_hole.py                        │
+│       → Shows ready holes                                │
+│    b. Write tests/refactor/test_h{N}_*.py (fails first) │
+│    c. Implement resolution                               │
+│    d. python scripts/validate_resolution.py H{N}         │
+│    e. python scripts/propagate.py H{N}                   │
+│    f. git commit -m "Resolve H{N}: ..."                  │
+└─────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────┐
+│ 4. FINAL REPORT                                          │
+│    python scripts/generate_report.py > REFACTOR_REPORT.md│
+│    → Comprehensive delta analysis                        │
+│    → Ready for merge                                     │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Scripts Included
+
+The skill includes these automation scripts:
+
+- **`discover_holes.py`** - Analyze codebase and generate REFACTOR_IR.md
+- **`next_hole.py`** - Show next resolvable holes based on dependencies
+- **`validate_resolution.py`** - Check if hole resolution satisfies constraints
+- **`propagate.py`** - Update dependent holes after resolution
+- **`generate_report.py`** - Create comprehensive delta report
+
+All scripts include `--help` for detailed usage.
+
+## Reference Documentation
+
+The skill includes comprehensive references:
+
+- **`HOLE_TYPES.md`** - Complete taxonomy of refactoring holes
+- **`CONSTRAINT_RULES.md`** - Constraint propagation patterns
+- **`VALIDATION_PATTERNS.md`** - Test patterns for validation
+
+Claude will read these as needed during the refactoring process.
+
+## Example Usage
+
+See `USAGE_PROMPT.md` for:
+- Complete example prompts
+- Troubleshooting guides
+- Advanced usage patterns
+- Best practices
+
+## When to Use This Skill
+
+Perfect for:
+- 🏗️ **Architecture refactoring** - Reorganizing code structure
+- 🔄 **Code consolidation** - Merging duplicate implementations
+- 🧹 **Technical debt reduction** - Systematic cleanup
+- 📈 **Complexity reduction** - Simplifying convoluted code
+- ✅ **Quality improvement** - Improving test coverage and code quality
+
+Not ideal for:
+- Small, localized changes (overkill)
+- Exploratory refactoring (too structured)
+- Breaking changes without compatibility needs (use simpler approach)
+
+## Key Principles
+
+1. **Test-Driven Everything** - Write tests before refactoring
+2. **Hole-Driven Progress** - Resolve unknowns systematically
+3. **Continuous Validation** - Never break characterization tests
+4. **Safe by Construction** - Work in branches, preserve history
+5. **Formal Completeness** - All holes resolved = refactoring complete
+
+## Compatibility
+
+- **Works with**: Python, JavaScript, TypeScript, Go, Rust, and other languages
+- **Requires**: Git repository with branch support
+- **Optional**: pytest (for Python), radon (for complexity analysis)
+
+## Support
+
+If you encounter issues:
+
+1. Check `USAGE_PROMPT.md` for troubleshooting prompts
+2. Review the reference documentation in the skill
+3. Ask Claude Code for help - it has access to all skill documentation
+
+## Meta-Consistency
+
+This skill practices what it preaches: it uses the typed holes methodology to refactor codebases, and can even use itself to improve itself! 🤯
+
+## License
+
+See LICENSE.txt in the skill package.
+
+---
+
+**Ready to refactor systematically? Install the skill and start with the prompts in USAGE_PROMPT.md!**