name

comparative-matrix

description

Generate structured comparisons and decision matrices across analyzed frameworks. Use when (1) comparing multiple frameworks or approaches side-by-side, (2) making architectural decisions between alternatives, (3) creating best-of-breed selection documentation, (4) synthesizing findings from multiple analysis skills into actionable decisions, or (5) producing recommendation reports for technical stakeholders.

Comparative Matrix

Synthesizes analysis outputs into structured decision frameworks.

Process

Collect analysis outputs from multiple frameworks
Normalize findings to comparable dimensions
Generate comparison matrix
Apply decision heuristics
Document recommendations with rationale

Comparison Dimensions

Core Dimensions (Always Include)

Dimension	What to Compare	Decision Criteria
Typing	Strict (Pydantic) vs Loose (dicts)	Team preference, runtime safety needs
Async	Native async vs sync-with-wrappers	Scalability requirements
State	Immutable vs mutable	Concurrency safety, debugging
Config	Code-first vs config-first	Flexibility vs discoverability
Extensibility	Composition vs inheritance	Maintainability, learning curve

Domain-Specific Dimensions

Dimension	When to Include
Reasoning Pattern	Comparing agent frameworks
Memory Strategy	Long-running agents
Multi-Agent	Orchestration systems
Observability	Production deployments
Tool Interface	Custom tool development

Matrix Template

## Best-of-Breed Matrix: [Analysis Title]

| Dimension | Framework A | Framework B | Framework C | **Recommendation** |
|:----------|:------------|:------------|:------------|:-------------------|
| **Typing** | Pydantic V1, deep nesting | TypedDict, flat | Loose dicts | *Pydantic V2, flat structures* |
| **Async** | Sync core, async wrapper | Native async | Mixed | *Native async required* |
| **State** | Mutable, in-place | Immutable copy | Hybrid | *Immutable preferred* |
| **Config** | YAML + Python | Pure Python | JSON | *Python for type safety* |
| **Extensibility** | Deep inheritance (6 layers) | Composition | Protocols | *Composition + Protocols* |

### Dimension Details

#### Typing
- **Framework A**: Uses Pydantic V1 with deeply nested models (Message → Content → Block → ...)
  - Pro: Full validation at boundaries
  - Con: Difficult to extend, version migration pain
- **Framework B**: TypedDict with flat structure
  - Pro: Simple, fast, IDE support
  - Con: No runtime validation
- **Recommendation**: Adopt Pydantic V2 with intentionally flat structures. Use TypedDict for internal types.

[Continue for each dimension...]

Decision Heuristics

Apply these heuristics when recommendations aren't obvious:

Scalability-First

IF high_concurrency_expected:
    PREFER native_async
    PREFER immutable_state
    PREFER stateless_tools

DX-First (Developer Experience)

IF team_is_small OR rapid_iteration:
    PREFER simple_inheritance_over_protocols
    PREFER code_first_config
    PREFER explicit_over_magic

Production-First

IF mission_critical:
    PREFER strict_typing
    PREFER comprehensive_observability
    PREFER explicit_error_boundaries

Output Artifacts

Summary Matrix - Single-page comparison table
Detailed Analysis - Per-dimension breakdown with evidence
Recommendation Document - Actionable decisions with rationale
Trade-off Log - Documented compromises and their justification

Example Output Structure

comparative-analysis/
├── matrix.md              # Summary comparison table
├── dimensions/
│   ├── typing.md          # Detailed typing analysis
│   ├── async.md           # Concurrency model analysis
│   └── ...
├── recommendations.md     # Final decisions
└── tradeoffs.md          # Documented compromises

Integration

Inputs from: All Phase 1 & 2 analysis skills
Outputs to: antipattern-catalog, architecture-synthesis