/tech-divergence

name: tech-divergence
description: Evaluate technical options with scoring matrix, trigger Gate 4 for significant decisions

Tech Divergence Skill

Evaluate technical implementation options using an 8-dimension scoring matrix. Low scores auto-proceed; high scores (>= 4) trigger Gate 4 for human decision.

When to Use

• During Plan Mode Phase 2 (Technical Diverge)
• Before committing to a specific architecture or pattern
• When multiple valid implementation approaches exist

Scoring Matrix (8 Dimensions)

Each dimension scores 0 (auto-proceed) or 1 (adds to checkpoint score):

| Dimension | 0 (Low Risk) | 1 (Checkpoint) | |-----------|--------------|----------------| | **Pattern** | Exists in codebase | New pattern required | | **Scope** | Single domain | Cross-domain impact | | **Data Model** | Add field to existing | New entity/table | | **Dependencies** | Use existing libs | New dependency | | **API Surface** | Internal only | Public/breaking change | | **Reversibility** | Easy to undo | Requires migration | | **Security** | Non-sensitive data | Auth/permissions | | **Performance** | Simple CRUD | Cache/queue/optimization |

Phase 1: Gather Context

1.1 Query Pattern Library (Notion)

Check if similar patterns exist:

API-query-database:
  database_id: "[PATTERN_LIBRARY_DB_ID]"
  filter:
    property: "Domain"
    select:
      equals: "[current domain]"

1.2 Search Codebase

SemanticSearch: "How is [similar feature] implemented?"
Grep: "[pattern name]" in relevant directories

1.3 Query Context7 (External Libraries)

If new libraries are being considered:

Context7 MCP:
1. resolve-library-id: libraryName = "[library]"
2. get-library-docs: topic = "best practices", mode = "info"

Phase 2: Score Each Dimension

For each of the 8 dimensions, evaluate and score:

## Technical Divergence Score

| Dimension | Score | Rationale |
|-----------|-------|-----------|
| Pattern | 0/1 | [Exists/New] |
| Scope | 0/1 | [Single/Cross-domain] |
| Data Model | 0/1 | [Field/Entity] |
| Dependencies | 0/1 | [Existing/New] |
| API Surface | 0/1 | [Internal/Public] |
| Reversibility | 0/1 | [Easy/Migration] |
| Security | 0/1 | [Non-sensitive/Auth] |
| Performance | 0/1 | [CRUD/Optimization] |
| **TOTAL** | [0-8] | |

Phase 3: Determine Path

If Score < 4: Auto-Proceed

## Technical Approach: Auto-Proceed

**Score:** [N]/8 (below threshold)

**Selected Approach:** [Describe the approach]

**Rationale:** 
- Pattern exists: [reference]
- Low cross-domain impact
- Easy to reverse if needed

Proceeding to Commit Plan...

If Score >= 4: Gate 4 (Human Checkpoint)

## Gate 4: Technical Approach Selection

**Score:** [N]/8 (threshold reached)

**Why human input needed:**
- [List dimensions that scored 1]

### Option A: [Name] (Conservative)

**Approach:** [Description]
**Effort:** S
**Risk:** Low
**Trade-off:** [What you give up]

### Option B: [Name] (Balanced)

**Approach:** [Description]
**Effort:** M
**Risk:** Medium
**Trade-off:** [What you give up]

### Option C: [Name] (Bold)

**Approach:** [Description]
**Effort:** L
**Risk:** Higher
**Trade-off:** [What you give up]

---

**Which approach would you like to proceed with?** (A / B / C)

*If you reject an option, I'll invoke decision-capture to record why.*

Phase 4: Record Decision

After Gate 4 selection:

1. If option rejected, invoke `decision-capture` skill 2. Record selected approach in context for Commit Plan 3. Update Pattern Library if new pattern established

Integration with Plan Mode

This skill is invoked during Plan Mode Phase 2:

Plan Mode Flow:
Phase 1: APPETITE → 
Phase 2: TECHNICAL DIVERGE (this skill) →
  If score < 4: Auto-proceed
  If score >= 4: Gate 4 → Human selects
Phase 3: COMMIT PLAN

MCP Tools Used

| Tool | Purpose | |------|---------| | Notion MCP | Query Pattern Library database | | Context7 MCP | Get library best practices | | SemanticSearch | Find existing codebase patterns | | Grep | Search for specific implementations |

Example Scoring

Low Score Example (Auto-Proceed)

**Feature:** Add a new column to existing table

| Dimension | Score | Rationale | |-----------|-------|-----------| | Pattern | 0 | Column additions done before | | Scope | 0 | Single domain (tables) | | Data Model | 0 | Adding field, not entity | | Dependencies | 0 | Using existing libs | | API Surface | 0 | Internal only | | Reversibility | 0 | Easy migration | | Security | 0 | Non-sensitive data | | Performance | 0 | Simple CRUD | | **TOTAL** | 0 | Auto-proceed |

High Score Example (Gate 4)

**Feature:** Add real-time collaboration

| Dimension | Score | Rationale | |-----------|-------|-----------| | Pattern | 1 | No WebSocket patterns yet | | Scope | 1 | Affects auth, tables, workflows | | Data Model | 1 | New presence entity | | Dependencies | 1 | Need socket.io | | API Surface | 1 | New WS endpoints | | Reversibility | 1 | Would need cleanup migration | | Security | 1 | User session handling | | Performance | 1 | Needs connection pooling | | **TOTAL** | 8 | Gate 4 required |

Invocation

Invoked automatically by Plan Mode Phase 2, or manually with "use tech-divergence skill".