tech-decision

What this skill does

# Tech Decision Skill

When evaluating a technical proposal or decision, follow this structured process. The goal is to turn casual "should we do X?" discussions into clear, data-driven analysis the team can act on.

**IMPORTANT**: Always save the output as a markdown file in the `project-decisions/` directory at the project root. Create the directory if it doesn't exist.

## 0. Output Setup

Before starting analysis, set up the output:
```bash
# Create project-decisions directory if it doesn't exist
mkdir -p project-decisions

# Generate filename from the decision topic
# Format: YYYY-MM-DD-short-description.md
# Example: 2026-02-19-bigquery-vs-looker-studio.md
```

The final document will be saved as:
```
project-decisions/YYYY-MM-DD-[kebab-case-topic].md
```

## 1. Understand the Proposal

### Parse the Request

Extract from the question or discussion:

- **What's being proposed?** — the specific change or decision
- **Who proposed it?** — context on their perspective
- **What problem does it solve?** — the underlying need
- **What's the current state?** — how things work today
- **What triggered this?** — why now? new tool, pain point, opportunity?
- **Who's affected?** — which teams, users, or systems

### Scan the Codebase for Context
```bash
# Find references to current tools/systems mentioned
grep -rn "[current-tool]" --include="*.ts" --include="*.js" --include="*.py" --include="*.yaml" --include="*.yml" --include="*.json" --include="*.md" --include="*.env*" . 2>/dev/null | grep -v "node_modules\|\.git" | head -20

# Find references to proposed tools/systems
grep -rn "[proposed-tool]" --include="*.ts" --include="*.js" --include="*.py" --include="*.yaml" --include="*.yml" --include="*.json" --include="*.md" --include="*.env*" . 2>/dev/null | grep -v "node_modules\|\.git" | head -20

# Check existing integrations and dependencies
cat package.json pyproject.toml docker-compose.yml 2>/dev/null | grep -iE "[tool-a]\|[tool-b]"

# Check for existing decision records
ls project-decisions/ docs/adr/ docs/decisions/ 2>/dev/null

# Check for related configuration
find . -name "*.config.*" -o -name "*.yaml" -o -name "*.yml" -o -name "*.toml" | grep -v "node_modules\|\.git" | head -20
```

## 2. Frame the Decision

### Decision Statement

Write a clear, neutral decision statement:
```
Decision: Should we [proposed change] instead of [current approach]?

Context: [1-2 sentences on why this came up]

Constraints:
- Timeline: [any deadline pressure]
- Budget: [cost considerations]
- Team capacity: [available engineering time]
- Technical constraints: [compatibility, legacy systems, compliance]
```

### Identify Options

Always evaluate at least 3 options:
```
Option A: Keep current approach (status quo / do nothing)
Option B: [The proposed change]
Option C: [A hybrid or alternative approach]
Option D: [Another alternative if applicable]
```

Never evaluate just the proposed option — always compare against the status quo and at least one alternative.

## 3. Analyze Each Option

For each option, evaluate:

### 3a. Feasibility Analysis

| Question | Assessment |
|----------|-----------|
| **Can we actually do this?** | Yes / Yes with caveats / Uncertain / No |
| **Do we have the skills?** | Team has experience / Learning needed / External help needed |
| **Do we have the tools?** | Available / Need to purchase / Need to build |
| **Does it integrate with our stack?** | Native support / Adapter available / Custom integration needed |
| **Are there blockers?** | None / Soft blockers / Hard blockers |
| **Is it proven?** | Mature & widely used / Emerging / Experimental |

### 3b. Effort & Timeline
```
Estimated effort breakdown:

| Phase | Duration | People | Notes |
|-------|----------|--------|-------|
| Research / Spike | Xd | 1 | Validate assumptions |
| Proof of Concept | Xd | 1-2 | Build minimal working version |
| Implementation | Xd | X | Full build |
| Migration | Xd | X | Move from current to new |
| Testing | Xd | X | Verify behavior preserved |
| Documentation | Xd | 1 | Update docs, runbooks |
| Rollout | Xd | X | Deploy, monitor, iterate |

Total: X person-days (~X weeks with Y people)
```

### 3c. Cost Analysis
```
| Cost Type | Current (Option A) | Proposed (Option B) | Alternative (Option C) |
|-----------|--------------------|--------------------|-----------------------|
| Monthly service cost | $X | $X | $X |
| Engineering effort (one-time) | $0 (already done) | $X (Y days × rate) | $X |
| Ongoing maintenance | X hrs/month | X hrs/month | X hrs/month |
| Training / ramp-up | $0 | $X | $X |
| Migration cost | $0 | $X | $X |
| Risk cost (if things go wrong) | $X | $X | $X |
| **Total Year 1** | **$X** | **$X** | **$X** |
| **Total Year 2+** | **$X/yr** | **$X/yr** | **$X/yr** |
```

### 3d. Risk Assessment

For each option:
```
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk 1] | High/Med/Low | High/Med/Low | [How to reduce] |
| [Risk 2] | High/Med/Low | High/Med/Low | [How to reduce] |
| [Risk 3] | High/Med/Low | High/Med/Low | [How to reduce] |
```

Common risks to evaluate:
- **Vendor lock-in** — how hard is it to switch away later?
- **Team knowledge** — does only one person understand this?
- **Scalability** — will this still work at 10x current scale?
- **Reliability** — what's the uptime/SLA guarantee?
- **Security** — does this introduce new attack vectors?
- **Data integrity** — could data be lost or corrupted during migration?
- **Rollback** — if it fails, how hard is it to revert?
- **Compatibility** — does it break existing integrations?
- **Maintenance burden** — will this add ongoing toil?
- **Compliance** — does this affect regulatory compliance (GDPR, SOC2, HIPAA)?

### 3e. Impact Analysis
```
| Area | Impact | Details |
|------|--------|---------|
| **Codebase** | X files changed | [which modules/services] |
| **API contracts** | Breaking / Non-breaking | [what changes for consumers] |
| **Database** | Schema change / No change | [migrations needed] |
| **Infrastructure** | New services / Config change | [what needs to be provisioned] |
| **CI/CD** | Pipeline changes needed | [new steps, env vars, secrets] |
| **Monitoring** | New dashboards/alerts | [what to monitor] |
| **Documentation** | Docs to update | [README, API docs, runbooks] |
| **Team workflows** | Process changes | [how daily work changes] |
| **Other teams** | Affected / Not affected | [who needs to know] |
| **End users** | Visible / Invisible | [UX changes, downtime] |
```

## 4. Comparison Matrix

### Side-by-Side Comparison
```
| Criteria | Weight | Option A (Status Quo) | Option B (Proposed) | Option C (Alternative) |
|----------|--------|-----------------------|--------------------|-----------------------|
| **Solves the problem** | 25% | ⭐⭐ (2/5) | ⭐⭐⭐⭐ (4/5) | ⭐⭐⭐ (3/5) |
| **Implementation effort** | 20% | ⭐⭐⭐⭐⭐ (5/5) | ⭐⭐ (2/5) | ⭐⭐⭐ (3/5) |
| **Ongoing cost** | 15% | ⭐⭐⭐ (3/5) | ⭐⭐⭐⭐ (4/5) | ⭐⭐⭐ (3/5) |
| **Risk** | 15% | ⭐⭐⭐⭐ (4/5) | ⭐⭐ (2/5) | ⭐⭐⭐ (3/5) |
| **Scalability** | 10% | ⭐⭐ (2/5) | ⭐⭐⭐⭐ (4/5) | ⭐⭐⭐⭐ (4/5) |
| **Team experience** | 10% | ⭐⭐⭐⭐⭐ (5/5) | ⭐⭐ (2/5) | ⭐⭐⭐ (3/5) |
| **Reversibility** | 5% | ⭐⭐⭐⭐⭐ (5/5) | ⭐⭐ (2/5) | ⭐⭐⭐ (3/5) |
| **Weighted Score** | 100% | **3.25** | **3.10** | **3.10** |
```

### Pros & Cons Summary

For each option:
```
Option B: [Proposed Change]

✅ Pros:
- [Specific, quantified benefit 1]
- [Specific, quantified benefit 2]
- [Specific, quantified benefit 3]

❌ Cons:
- [Specific, quantified drawback 1]
- [Specific, quantified drawback 2]
- [Specific, quantified drawback 3]

⚠️ Unknowns:
- [Thing we don't know yet that could change the analysis]
- [Assumption that needs validation]
```

## 5. Recommendation

### Decision Framework

Use this framework to make the recommendation:
```
IF the proposal clearly solves a real problem
AND the effort is justified by the benefit
AND the risks are manageable
AND the team has capacity
→ RECOMMEND: Proceed

IF the proposal solves