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".