From copilot-cli-toolkit
Discovers natural abstractions using Commonality Variability Analysis (CVA). Builds matrices from multiple similar requirements to reveal commonalities, variabilities, and design patterns.
How this skill is triggered — by the user, by Claude, or both
Slash command
/copilot-cli-toolkit:cva-analysisclaude-sonnet-4-6The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Commonality Variability Analysis (CVA) is a systematic technique for discovering abstractions from requirements. Instead of choosing patterns first, you build a matrix showing what's COMMON (constant across use cases) vs what VARIES (differs between cases). Patterns emerge naturally from the matrix structure.
Commonality Variability Analysis (CVA) is a systematic technique for discovering abstractions from requirements. Instead of choosing patterns first, you build a matrix showing what's COMMON (constant across use cases) vs what VARIES (differs between cases). Patterns emerge naturally from the matrix structure.
Core Insight: Rows (commonalities) map to Strategy pattern. Columns (variabilities) map to Abstract Factory pattern. The matrix reveals whether abstraction is needed at all.
From CLAUDE.md Design Philosophy: "Greatest vulnerability is wrong or missing abstraction." CVA prevents wrong abstractions by making pattern selection evidence-based, not intuition-based.
Activate CVA when you encounter:
discover abstractions for [domain]run CVA analysis on [requirements]commonality variability analysisprevent wrong abstractionwhat patterns emerge from [use cases]| Phase | Purpose | Input | Output | Time |
|---|---|---|---|---|
| 1. Identify Commonalities | Find what's constant across ALL use cases | Use cases/requirements | List of commonalities (matrix rows) | 5-10 min |
| 2. Identify Variabilities | Find what VARIES between use cases | Commonalities + use cases | List of variabilities (matrix columns) | 5-10 min |
| 3. Build Matrix | Visualize commonality × variability relationships | Rows + columns | CVA matrix (Markdown table) | 5-15 min |
| 4. Map to Patterns | Translate matrix structure to design patterns | Completed matrix | Pattern recommendations + rationale | 5-10 min |
| 5. Validate & Handoff | Validate choices, route to appropriate agents | Pattern recommendations | Validation report + ADR stub | 5-10 min |
Total Time: Quick (15 min), Standard (30 min), Deep (60 min)
Use CVA when:
Do NOT use CVA when:
Purpose: Establish what is ALWAYS true across ALL use cases. This becomes the stable foundation.
Steps:
Example (Payment Processing):
Use Case 1: Credit card payment
Use Case 2: PayPal payment
Use Case 3: Bank transfer
Commonalities (ALL cases need):
- Validate payment amount
- Authorize transaction
- Record transaction
- Handle transaction errors
Verification:
Failure Handling: If no commonalities exist, use cases may be unrelated. Analyze separately or reconsider grouping.
Purpose: Discover what VARIES between use cases. This reveals extension points where Strategy or Abstract Factory patterns may apply.
Steps:
Example (continuing Payment Processing):
Commonality: Validate payment amount
Variations:
- Credit Card: Check card limit, validate CVV
- PayPal: Check PayPal balance, validate account status
- Bank Transfer: Check account balance, validate routing number
Commonality: Authorize transaction
Variations:
- Credit Card: Contact card issuer API
- PayPal: OAuth flow with PayPal
- Bank Transfer: ACH authorization
Verification:
Failure Handling: If all variability (no commonality), design may be too broad. Narrow scope or reconsider.
Purpose: Create visual artifact showing commonality × variability relationships. Makes implicit design explicit for team discussion.
Steps:
scripts/export-cva-matrix.pyExample Matrix:
| Commonality | Credit Card | PayPal | Bank Transfer |
|---|---|---|---|
| Validate amount | Check card limit, CVV | Check PayPal balance, account | Check account balance, routing |
| Authorize | Card issuer API | PayPal OAuth | ACH authorization |
| Record | Log to CardTransactionDB | Log to PayPalTransactionDB | Log to BankTransactionDB |
| Handle errors | Card decline codes | PayPal error codes | ACH rejection codes |
Interpretation:
Verification:
Failure Handling: If matrix shows no useful patterns, abstraction may not be beneficial. Document rationale for concrete implementation.
Purpose: Translate matrix structure to design patterns. Patterns EMERGE from analysis, not imposed.
Steps:
Read ROWS (commonalities):
IAuthorizationStrategyRead COLUMNS (variabilities):
CreditCardPaymentFactoryCheck for multidimensional variability:
Document recommendations:
Example Output:
## Pattern Recommendations
### Primary: Abstract Factory Pattern
**Rationale**: Each payment method (Credit Card, PayPal, Bank Transfer) requires a coherent family of related operations. Matrix columns show consistent product families.
**Implementation**:
```csharp
public interface IPaymentFactory {
IAmountValidator CreateValidator();
ITransactionAuthorizer CreateAuthorizer();
ITransactionRecorder CreateRecorder();
IErrorHandler CreateErrorHandler();
}
public class CreditCardPaymentFactory : IPaymentFactory {
// Concrete implementations from "Credit Card" column
}
Alternative: Strategy pattern per row (4 separate strategies). Rejected because operations are not independent - they share payment method context. Factory keeps cohesion.
**Create ADR stub** for architect agent:
```markdown
# ADR-XXX: Payment Processing Abstraction
## Context
CVA matrix revealed 3 payment methods with 4 common operations, each varying by method.
## Decision
Use Abstract Factory pattern with `IPaymentFactory` per method.
## Rationale
- Matrix columns show coherent product families
- Operations share payment method context (not independent)
- New payment methods extend without modifying existing
## Alternatives Considered
- Strategy per operation: Rejected (operations not independent, loses cohesion)
- No abstraction: Rejected (3 methods with clear variations justify abstraction per YAGNI threshold)
Verification:
Failure Handling: If no patterns fit cleanly, document rationale for concrete implementation. Abstraction may not be warranted yet.
Purpose: Validate abstraction choices and route to appropriate agents for review.
Steps:
Run validation script:
python3 .claude/skills/cva-analysis/scripts/validate-cva-matrix.py cva-matrix.md
Route to decision-critic (if abstraction recommended):
# Use decision-critic skill to validate abstraction choice
/decision-critic "Validate Abstract Factory pattern for payment processing per CVA analysis"
Route to architect agent (for ADR creation):
# Hand off ADR stub to architect agent
Task(subagent_type="architect", prompt="Create ADR from CVA analysis stub")
Document reassessment triggers:
## Reassessment Triggers
Re-run CVA when:
- 3+ new payment methods added
- Major architectural shift (e.g., microservices split)
- Performance issues with current abstraction
- Team feedback: abstraction is too complex or not pulling weight
Outputs:
Verification:
Failure Handling: If validation fails, return to earlier phase based on issue:
| Anti-Pattern | Why Bad | Example | Instead |
|---|---|---|---|
| Pattern-First Design | Violates CVA principle: patterns emerge, not imposed. Leads to wrong abstractions. | Decide "we need Strategy pattern" BEFORE running CVA | Run CVA first. Let matrix reveal pattern. If no pattern emerges, abstraction may not be needed. |
| Forcing Abstractions | Creates complexity without benefit. Worse than no abstraction per CLAUDE.md. | CVA shows no variability, but create Strategy anyway "for future" | When CVA shows no variability, explicitly document decision NOT to abstract. Revisit when variability emerges. |
| Skipping Matrix Visualization | Loses pedagogical and collaborative benefits. Matrix makes assumptions explicit. | Identify commonalities/variabilities mentally, skip matrix, jump to pattern | Always create visual matrix (Markdown table minimum). Use for team review, ADR rationale. |
| Analysis Paralysis | CVA is a tool, not an end. Over-analysis wastes time. | Spend 3 hours on CVA for 2 simple use cases | Use tiered approach: Quick (15 min) for simple, Standard (30 min) moderate, Deep (60 min) architectural. Set timer. |
| Ignoring Temporal Dimension | Today's constant may be tomorrow's variable. | CVA assumes "currency" constant (USD only). 6 months later, need multi-currency. | Include "Future Variations" column for anticipated changes. Balance YAGNI with known roadmap. |
| Using CVA for Single Use Case | CVA requires 2+ cases to identify commonality/variability. | Run CVA on payment before any other transaction exists | Wait for 2nd use case (YAGNI), OR document anticipated cases with stakeholder validation. |
CVA produces ADR stub with pattern rationale. Architect agent creates formal ADR.
Handoff Protocol:
Task(subagent_type="architect", prompt="Create ADR from CVA analysis at cva-payment-processing.md")
Validates abstraction choices discovered via CVA. Applies inversion thinking to pattern recommendation.
Usage:
/decision-critic "Validate Abstract Factory pattern for payment processing per CVA matrix"
Challenges whether abstraction is needed at all. Use when CVA is borderline (minimal variability).
Usage:
Task(subagent_type="independent-thinker", prompt="Challenge whether payment abstraction is justified given only 2 current methods")
After completing CVA:
python3 scripts/validate-cva-matrix.py [file]Re-run CVA when:
Choose depth based on decision impact:
| Tier | Time | Use Cases | When to Use |
|---|---|---|---|
| Quick | 15 min | 2-3 | Simple decisions, clear patterns, low risk |
| Standard | 30 min | 3-5 | Moderate complexity, some uncertainty, medium risk |
| Deep | 60 min | 6+ | Architectural decisions, high uncertainty, high risk |
Time-boxing: Set timer, commit to best-available analysis when time expires. CVA is a tool, not a perfectionist exercise.
See references/matrix-building-examples.md for complete .NET examples:
Check CVA matrix completeness and suggest patterns.
Usage:
python3 .claude/skills/cva-analysis/scripts/validate-cva-matrix.py cva-matrix.md
Exit Codes:
Create empty matrix template from user input.
Usage:
python3 .claude/skills/cva-analysis/scripts/generate-cva-template.py \
--commonalities "Validate,Authorize,Record,Handle errors" \
--variabilities "CreditCard,PayPal,BankTransfer" \
--output cva-matrix.md
Convert Markdown table to Mermaid diagram for presentations.
Usage:
python3 .claude/skills/cva-analysis/scripts/export-cva-matrix.py \
--input cva-matrix.md \
--format mermaid \
--output cva-diagram.mmd
Pattern Mapping: Add new pattern types beyond Strategy/Abstract Factory
references/pattern-mapping-guide.mdMatrix Formats: Add export formats beyond Markdown
scripts/export-cva-matrix.py --format <json|plantuml|csv>Multidimensional Analysis: Handle complex cases with 3+ axes
references/multidimensional-cva.mdAI Integration: Automated pattern suggestion
npx claudepluginhub rjmurillo/ai-agentsDiscovers natural abstractions using Commonality Variability Analysis. Builds matrices of commonalities and variabilities from multiple similar requirements to inform evidence-based pattern selection.
Structures thinking across strategic, tactical, and operational layers. Use for top-down decomposition, bottom-up aggregation, cross-layer translation, or maintaining consistency between principles and implementation.
Explores trade-offs in design and architecture decisions as a thinking partner, helping users understand options and make informed choices without recommending solutions.