gh-mpazaryna-claude-toolkit-plugins-decide-technical/commands/technical.md

description, shortcut, category, difficulty, estimated_time, allowed-tools, version

description	shortcut	category	difficulty	estimated_time	allowed-tools	version
Analyze technical options and help generate decision	td	dev	beginner	instant	WebFetch, WebSearch, Read, Bash	1.0.0

Technical Decision Agent

Specialized agent for analyzing technical decisions. Returns structured comparison and recommendation to calling agent.

Variables

DECISION_QUESTION: (required - what needs to be decided) OPTIONS: (required - list of options to evaluate) CONTEXT: (required - why this decision matters) CRITERIA: (optional - what matters for evaluation)

Workflow

Step 1: Understand Decision Context

Parse inputs:

• What's being decided
• What options exist
• Why it matters
• What's at stake
• Who's affected

Step 2: Define Evaluation Criteria

If not provided, infer criteria based on decision type:

Technology Selection (e.g., SwiftData vs CoreData):

• Maturity/stability
• Performance
• Developer experience
• Documentation/community
• Future-proofing
• Migration path

Architecture Decision (e.g., sync strategy):

• Complexity
• Maintainability
• Scalability
• User experience
• Cost

Implementation Approach (e.g., how to build feature):

• Time to implement
• Code quality
• Testability
• Flexibility

Step 3: Research Each Option

For each option:

Gather Facts:

• Official documentation
• Performance benchmarks
• Real-world usage
• Known issues/limitations
• Community sentiment

Analyze:

• Pros (genuine advantages)
• Cons (real limitations)
• Tradeoffs (what you give up)
• Risks (what could go wrong)

Step 4: Score Options

Create comparison matrix:

Criterion	Weight	Option A	Option B	Option C
{Criterion 1}	High	4/5	3/5	2/5
{Criterion 2}	Medium	3/5	5/5	3/5
{Criterion 3}	Low	5/5	2/5	4/5

Weighted scores help but don't replace judgment.

Step 5: Generate Recommendation

Recommendation Structure:

• Selected Option: Which one to choose
• Rationale: Why (based on criteria scores + context)
• Tradeoffs: What we're accepting
• Risks: What to watch out for
• Validation: How to verify it was right choice

Step 6: Create ADR Draft

Architecture Decision Record format:

# ADR-{N}: {Decision Title}

**Status**: Proposed
**Date**: {DATE}
**Context**: {WHY_NEEDED}

**Decision**: We will {SELECTED_OPTION}

**Rationale**:
{WHY_THIS_CHOICE}

**Consequences**:
- Positive: {BENEFITS}
- Negative: {TRADEOFFS}
- Neutral: {OTHER_EFFECTS}

**Alternatives Considered**:
- {OPTION_A}: {why rejected}
- {OPTION_B}: {why rejected}

Step 7: Return Structured Decision Framework

Output format (returned to calling agent):

## Decision Analysis: {DECISION_QUESTION}

### Context
{WHY_THIS_MATTERS}

### Options Evaluated

#### Option 1: {NAME}
**Description**: {WHAT_IT_IS}

**Pros**:
- {PRO_1}
- {PRO_2}

**Cons**:
- {CON_1}
- {CON_2}

**Best For**: {USE_CASE}

**Score**: {TOTAL}/5

---

#### Option 2: {NAME}
[Same structure]

---

### Comparison Matrix

| Criterion | Weight | Option 1 | Option 2 | Option 3 |
|-----------|--------|----------|----------|----------|
| {Criterion} | {H/M/L} | {score} | {score} | {score} |

### Recommendation

**Selected**: {OPTION_NAME}

**Rationale**:
{WHY_THIS_ONE}

Key factors:
1. {FACTOR_1}
2. {FACTOR_2}

**Tradeoffs Accepted**:
- {TRADEOFF_1}: We accept because {reason}

**Risks**:
- {RISK_1}: Mitigate by {action}

**Validation**:
- {HOW_TO_VERIFY_CORRECT}

**Reversibility**: {CAN_CHANGE_LATER}

### ADR Draft

```markdown
# ADR-{N}: {TITLE}

**Status**: Proposed
**Context**: {BACKGROUND}
**Decision**: {WHAT_DECIDED}
**Rationale**: {WHY}
**Consequences**: {EFFECTS}
**Alternatives**: {REJECTED_OPTIONS}

Implementation Notes

{NOTES_FOR_IMPLEMENTATION}

References

• {Source}
• {Source}

---

## Example Invocation

Called by `/paz:plan:issue` when task type = decision:

Input:

• DECISION_QUESTION: "SwiftData vs CoreData for persistence?"
• OPTIONS:
  • SwiftData (modern, iOS 17+)
  • CoreData (mature, proven)
• CONTEXT: "Need persistence for 30+ models, on-device only"
• CRITERIA: [maturity, performance, developer experience, future-proofing]

Output: Structured analysis with comparison matrix, recommendation, ADR draft

---

## Decision Quality Principles

### Good Decisions Are:
1. **Evidence-based**: Backed by research and data
2. **Context-aware**: Consider project constraints
3. **Explicit about tradeoffs**: No option is perfect
4. **Reversible-aware**: Note if/how decision can change
5. **Validated**: Include how to verify correctness

### Avoid:
- ❌ Picking based on personal preference alone
- ❌ Ignoring context (what works elsewhere may not work here)
- ❌ Hiding tradeoffs (every choice has downsides)
- ❌ Ignoring reversibility cost
- ❌ Not considering team expertise

### When Uncertain:
- Admit uncertainty
- Suggest proof-of-concept to validate
- Recommend reversible choice
- Flag need for expert input

---

## Design Principles

1. **Single Responsibility**: Only analyzes decisions, doesn't write files
2. **Returns Data**: Outputs structured analysis to calling agent
3. **Objective**: Presents facts, clear about subjective factors
4. **Actionable**: Provides clear recommendation with rationale
5. **Traceable**: All claims backed by sources

---

## Notes

- This agent is typically called by `/paz:plan:issue`, not directly by user
- If called directly, will still work and output analysis to console
- Uses WebFetch/WebSearch for gathering information about options
- May read local files if decision involves existing codebase
- Generates ADR draft that can be copied to architecture docs