complexity-assessment

What this skill does

# Complexity Assessment

Evaluate task complexity before planning to ensure appropriate workflow depth and artifact structure.

## Contextd Integration

If contextd MCP is available:
- `memory_search` to find similar past assessments
- `memory_record` for tier recommendations with rationale
- `memory_outcome` to track assessment accuracy over time
- `branch_create/return` for isolated assessment

If contextd is NOT available:
- Assessment runs inline (still works)
- No persistence of tier decisions
- No historical comparison available

## When to Use

This skill is called by `/brainstorm` Phase 2 to determine:
- Question depth (SIMPLE: 3-5, STANDARD: 8-12, COMPLEX: 15+)
- GitHub artifact structure (single issue vs epic + sub-issues vs project board)
- Worktree recommendation
- Context branch budget allocation

---

## 7 Dimensions

Assess each dimension and aggregate to determine tier:

### 1. Scope
**Question:** How many files will be touched?

| Files | Score | Indicator |
|-------|-------|-----------|
| 1-2 | 1 | Single component, localized change |
| 3-10 | 2 | Multiple components, cross-cutting |
| 10+ | 3 | System-wide, architectural change |

### 2. Integration
**Question:** What external dependencies are involved?

| Dependencies | Score | Indicator |
|--------------|-------|-----------|
| None | 1 | Self-contained, no external calls |
| 1-2 APIs/services | 2 | Moderate integration work |
| 3+ APIs/services | 3 | Complex orchestration required |

### 3. Infrastructure
**Question:** Are config/infra changes required?

| Changes | Score | Indicator |
|---------|-------|-----------|
| None | 1 | Code-only change |
| Config files | 2 | Environment variables, feature flags |
| New infra | 3 | Database, Docker, cloud resources |

### 4. Knowledge
**Question:** What domain expertise is required?

| Expertise | Score | Indicator |
|-----------|-------|-----------|
| Familiar patterns | 1 | Standard CRUD, common patterns |
| Some research | 2 | New library, unfamiliar domain |
| Deep expertise | 3 | Security, performance, compliance |

### 5. Risk
**Question:** What's the blast radius if something goes wrong?

| Risk | Score | Indicator |
|------|-------|-----------|
| Low | 1 | Easily reversible, non-critical path |
| Medium | 2 | User-facing, requires testing |
| High | 3 | Data integrity, security, payments |

### 6. Testing (New)
**Question:** What testing effort is required?

| Testing | Score | Indicator |
|---------|-------|-----------|
| Minimal | 1 | Unit tests only, existing patterns |
| Moderate | 2 | Integration tests, new test fixtures |
| Extensive | 3 | E2E tests, performance tests, security audits |

### 7. Decomposability (New)
**Question:** Can this task be split into independent units?

| Decomposability | Score | Indicator |
|-----------------|-------|-----------|
| Easily decomposable | 1 | Clear subtasks, no shared state |
| Partially decomposable | 2 | Some dependencies between subtasks |
| Monolithic | 3 | Tightly coupled, must be done together |

---

## Risk Multipliers

Apply these multipliers to the base score when present:

| Factor | Multiplier | When to Apply |
|--------|------------|---------------|
| Security-sensitive | 1.2x | Auth, encryption, user data, API keys |
| Data migration | 1.3x | Schema changes, data transformations |
| Breaking changes | 1.2x | API changes, deprecated features |
| Technical debt | 1.1x | Working in legacy/poorly-tested code |
| Time pressure | 1.1x | Urgent deadline, reduced review time |

**Calculation:** `adjusted_score = base_score * highest_applicable_multiplier`

---

## Confidence Scoring

Every assessment includes a confidence percentage (0-100%):

| Confidence | Range | Criteria |
|------------|-------|----------|
| High | 80-100% | Clear requirements, familiar domain, similar past tasks |
| Medium | 50-79% | Some ambiguity, partial familiarity |
| Low | 0-49% | Unclear scope, unfamiliar domain, novel problem |

**When confidence < 60%:** Use `AskUserQuestion` to clarify ambiguous dimensions before finalizing tier.

**Confidence factors:**
- Requirements clarity (+/- 20%)
- Domain familiarity (+/- 15%)
- Historical data available (+/- 15%)
- Codebase familiarity (+/- 10%)

---

## Team Velocity Factors

Adjust expectations based on team context:

| Factor | Impact | Consideration |
|--------|--------|---------------|
| Team size | +/- 1 tier | Solo dev may need COMPLEX timeline adjustment |
| Experience level | +/- 1 dimension score | Junior devs add +1 to Knowledge dimension |
| Codebase familiarity | +/- 1 dimension score | New team members add +1 to Scope |
| Concurrent priorities | +/- 1 tier | High WIP may require elevated treatment |

---

## Tier Calculation

Sum scores across all 7 dimensions (max 21):

| Total Score | Tier | Characteristics |
|-------------|------|-----------------|
| 7-11 | SIMPLE | Quick change, minimal planning needed |
| 12-16 | STANDARD | Moderate complexity, structured approach |
| 17-21 | COMPLEX | High complexity, extensive planning required |

**After multipliers:** Round to nearest integer before tier assignment.

---

## Structured Output

Return assessment as JSON for downstream consumption:

```json
{
  "tier": "STANDARD",
  "confidence": 75,
  "confidence_justification": "Clear scope but unfamiliar OAuth library",
  "base_score": 14,
  "adjusted_score": 16.8,
  "multipliers_applied": ["security-sensitive"],
  "dimensions": {
    "scope": { "score": 2, "rationale": "Auth routes, middleware, user model, frontend" },
    "integration": { "score": 2, "rationale": "OAuth provider API" },
    "infrastructure": { "score": 2, "rationale": "Environment variables, session config" },
    "knowledge": { "score": 2, "rationale": "OAuth2 flow, security best practices" },
    "risk": { "score": 3, "rationale": "Security-critical, user data" },
    "testing": { "score": 2, "rationale": "Integration tests for OAuth flow" },
    "decomposability": { "score": 1, "rationale": "Backend/frontend can be parallelized" }
  },
  "decomposition_suggestions": null,
  "historical_comparison": "Similar OAuth task took 3 iterations (Issue #45)",
  "team_velocity_adjustments": null,
  "integration_hints": {
    "github_artifact": "epic_with_sub_issues",
    "context_branch_budget": 8192,
    "worktree_recommended": true
  },
  "recommended_agents": {
    "always": ["code-quality-reviewer"],
    "if_go": ["go-reviewer"],
    "if_security_sensitive": ["security-reviewer", "vulnerability-reviewer"],
    "if_api_change": ["user-persona-reviewer", "documentation-reviewer"],
    "all": false
  },
  "intent_confirmation": {
    "required": true,
    "mode": "STANDARD"
  }
}
```

---

## Tier Implications

### SIMPLE (7-11)
- **Questions:** 3-5 quick clarifications
- **GitHub:** Single Issue with checklist
- **Worktree:** Optional, can work in main
- **Review:** Standard consensus review
- **Context branch budget:** 4096 tokens
- **Testing:** Unit tests, 70%+ coverage on new code

### STANDARD (12-16)
- **Questions:** 8-12 detailed questions
- **GitHub:** Epic Issue + sub-Issues
- **Worktree:** Recommended for isolation
- **Review:** Full consensus review
- **Context branch budget:** 8192 tokens
- **Testing:** Unit + integration tests, 80%+ coverage

### COMPLEX (17-21)
- **Questions:** 15+ comprehensive questions
- **GitHub:** Epic + sub-Issues + Project board
- **Worktree:** Required for isolation
- **Review:** Full consensus + additional scrutiny
- **Context branch budget:** 16384 tokens
- **Testing:** Unit + integration + E2E, 90%+ coverage, security audit

---

## Intent Confirmation Gating

After tier determination, include an `intent_confirmation` field in the output to signal the **caller** whether intent confirmation is recommended:

| Tier | Recommendation |
|------|----------------|
| SIMPLE (7-11) | `"intent_confirmation": "none"` - Caller should auto-proceed. |
| STANDARD (12-16) | `"intent_confirmation": "standard"` - Caller should invoke intent-confirmation skill