hierarchical-matching-systems_skill

Overview

This skill provides pragmatic procedures and checklists for architecting, implementing, reviewing, and debugging hierarchical matching systems. It covers problem classification, translating business rules into formal constraints, algorithm selection, data model and interface design, and disciplined debugging sequences for instability, constraint violations, preference alignment, hierarchy traversal, and performance. Follow the checklists in order to avoid hidden matching bugs.

How this skill works

The skill inspects system requirements and maps them to constraint types (capacity, coupling, exclusion, ordering, soft preferences). It prescribes architecture phases: requirements translation, algorithm selection, data modeling, interface contracts, and testing. For live issues it runs a step-by-step diagnosis: classify the symptom, trace encoding and enforcement, verify preference transformations, visualize hierarchy traversal, and profile performance to isolate root causes.

When to use it

• Designing a new two-sided or one-sided matching system
• Translating business rules into formal constraints and invariants
• Debugging unstable or non-deterministic matches
• Investigating constraint violations or unexpected match outcomes
• Architecting multi-level or hierarchical matching across orgs/taxonomies

Best practices

• Classify the problem up front (two-sided, hierarchical, weighted, constrained) and record it
• Translate every business rule into a formal, testable constraint and mark hard vs soft
• Choose algorithms only after verifying they support required hard constraints and scale
• Canonicalize inputs and deterministic tie-breaking to eliminate instability
• Add property tests for determinism, validity, stability, and edge cases; include regression tests from production

Example use cases

• Student-school assignment with capacity, siblings coupling, and priority groups
• Job-worker assignment with skill-weighted scores and exclusion constraints
• Entity resolution across nested taxonomies where parent constraints must propagate
• Reviewing matching logic where identical inputs produce different outputs
• Optimizing assignment for weighted objectives while preserving hard exclusions