hierarchical-matching-systems

# Hierarchical Matching Systems

This skill provides rigid diagnostic and architectural procedures for hierarchical matching systems. Follow checklists exactly—matching bugs often hide in skipped steps.

## Quick Reference

- **Algorithm selection**: See [references/decision-guide.md](references/decision-guide.md)
- **Algorithm details**: See [references/algorithms.md](references/algorithms.md)

---

## 1. Problem Classification Checklist

Before any work, classify the problem. Check ALL that apply:

```
□ TWO-SIDED: Both sides have preferences (students↔schools, workers↔jobs)
□ ONE-SIDED: Only one side has preferences (tasks→workers, items→bins)
□ HIERARCHICAL: Entities exist at multiple levels (org→dept→team→person)
□ WEIGHTED: Matches have costs/scores to optimize
□ CONSTRAINED: Hard limits exist (capacity, exclusions, required pairings)
□ STABLE: Solution must resist defection (no blocking pairs)
□ OPTIMAL: Solution must minimize/maximize objective function
□ FUZZY: Entities may partially match (entity resolution, deduplication)
```

Classification determines algorithm family. Proceed to Section 2 for architecture or Section 3 for debugging.

---

## 2. Architecture Procedure

Follow these phases in order when designing a new matching system.

### Phase 2.1: Requirements Translation

Convert each business requirement into formal constraints:

| Business Requirement | Constraint Type | Formal Expression |
|---------------------|-----------------|-------------------|
| "Each student gets one school" | Capacity | `|matches(s)| = 1 ∀ student s` |
| "Schools have seat limits" | Capacity | `|matches(school)| ≤ capacity` |
| "Siblings must be together" | Coupling | `school(s1) = school(s2) if siblings(s1,s2)` |
| "Student X cannot attend Y" | Exclusion | `(X, Y) ∉ matches` |
| "Priority for residents" | Preference ordering | `rank(resident) < rank(non-resident)` |

**Checklist:**
```
□ List ALL business requirements
□ Classify each as: capacity | coupling | exclusion |