| 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
