Complexity Assessment

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?

2. Integration

Question: What external dependencies are involved?

3. Infrastructure

Question: Are config/infra changes required?

4. Knowledge

Question: What domain expertise is required?

5. Risk

Question: What's the blast radius if something goes wrong?

6. Testing (New)

Question: What testing effort is required?

7. Decomposability (New)

Question: Can this task be split into independent units?

Risk Multipliers

Apply these multipliers to the base score when present:

Calculation: adjusted_score = base_score * highest_applicable_multiplier

Confidence Scoring

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

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:

Tier Calculation

Sum scores across all 7 dimensions (max 21):

After multipliers: Round to nearest integer before tier assignment.

Structured Output

Return assessment as JSON for downstream consumption:

{
  "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:

Integration Note

This skill does NOT invoke intent-confirmation itself. It outputs a recommendation that the calling workflow uses to decide whether to invoke intent-confirmation. The typical workflow is:

Caller (e.g., /brainstorm, /plan):
  1. Invoke complexity-assessment → returns tier + intent_confirmation field
  2. If intent_confirmation != "none":
     → Invoke intent-confirmation skill with the recommended mode
     → Wait for user confirmation
  3. Proceed with execution

This avoids a circular dependency between the two skills.

DETAILED Mode (COMPLEX only)

For COMPLEX tasks, the intent preview includes:

• Full decomposition plan with subtask dependencies
• Risk factors and mitigation strategy
• Estimated resource usage (agents, branches, tokens)
• Explicit list of files to be modified
• User must respond with explicit "Yes" (not just acknowledgment)

Why Gate on Complexity?

• SIMPLE tasks should not slow down developer flow with unnecessary confirmation
• STANDARD tasks benefit from a pause to ensure alignment
• COMPLEX tasks require explicit buy-in because rollback cost is high
• Research (JetBrains NeurIPS 2025) shows observation masking is 52% cheaper than full summarization; confirming intent early avoids wasted work on misunderstood requirements

Review Agent Selection

Include a recommended_agents field in the structured output based on the assessment. This allows the consensus-review skill to perform adaptive agent selection without re-analyzing the diff.

Output Field

{
  "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
  }
}

Selection Logic

Conditional Agent Triggers

These are derived from the dimension scores:

Integration with consensus-review

The consensus-review skill reads recommended_agents from the assessment output:

1. Run complexity-assessment → get tier + recommended_agents
2. Pass recommended_agents to consensus-review adaptive agent selection
3. Consensus-review merges recommended_agents with its own override rules
4. Final agent set = union(recommended_agents, override_agents)

Integration with Other Skills

github-planning Integration

Tier determines GitHub artifact structure:

context-folding Integration

Tier determines branch budget:

Decomposition Suggestions

For COMPLEX tasks (score 17+), provide decomposition suggestions:

{
  "decomposition_suggestions": [
    {
      "subtask": "Backend OAuth integration",
      "estimated_tier": "STANDARD",
      "dependencies": [],
      "can_parallelize": true
    },
    {
      "subtask": "Frontend auth UI components",
      "estimated_tier": "SIMPLE",
      "dependencies": [],
      "can_parallelize": true
    },
    {
      "subtask": "Session management middleware",
      "estimated_tier": "SIMPLE",
      "dependencies": ["Backend OAuth integration"],
      "can_parallelize": false
    }
  ],
  "parallelization_potential": "2 of 3 subtasks can run in parallel",
  "recommended_approach": "Split into 3 issues, assign backend and frontend in parallel"
}

Ambiguity Handling

When confidence < 60%, use AskUserQuestion to clarify:

AskUserQuestion(
  question: "I'm uncertain about the complexity of this task. To provide an accurate assessment, I need clarification on:",
  options: [
    "What external services/APIs will this integrate with?",
    "Are there existing tests I should reference for patterns?",
    "What's the expected timeline pressure?",
    "Are there schema/database changes involved?"
  ],
  allow_custom: true
)

After clarification: Re-score affected dimensions and recalculate tier.

Historical Comparison

When contextd is available, search for similar past assessments:

# Search for similar tasks
mcp__contextd__memory_search(
  project_id: "<project>",
  query: "<task description keywords>",
  tags: ["complexity-assessment"]
)

Include in output:

• Similar past tasks and their actual outcomes
• Iteration count (how many rounds to complete)
• Assessment accuracy (predicted vs actual complexity)

Example output:

Historical comparison: "Similar OAuth task (Issue #45) was assessed as STANDARD,
took 3 iterations to complete. Assessment was accurate."

Contextd Recording

Store assessment in contextd with full rationale:

mcp__contextd__memory_record(
  project_id: "<project>",
  title: "Complexity assessment: <task-summary>",
  content: JSON.stringify({
    tier: "<tier>",
    confidence: <0-100>,
    base_score: <sum>,
    adjusted_score: <after multipliers>,
    dimensions: { <all 7 with scores and rationale> },
    multipliers: [<applied multipliers>],
    decomposition: <suggestions if COMPLEX>,
    integration_hints: { <github, context-folding settings> }
  }),
  outcome: "success",
  tags: ["complexity-assessment", "<tier>", "confidence-<high|medium|low>"]
)

Example Assessment

Task: "Add user authentication with OAuth2"

Base Score: 14/21 Multiplier: 1.2x (security-sensitive) Adjusted Score: 16.8 -> 17 = COMPLEX (borderline) Confidence: 75% (clear scope, unfamiliar library)

JSON Output:

{
  "tier": "COMPLEX",
  "confidence": 75,
  "confidence_justification": "Clear scope but unfamiliar OAuth library",
  "base_score": 14,
  "adjusted_score": 17,
  "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": [
    { "subtask": "Backend OAuth routes", "estimated_tier": "STANDARD", "can_parallelize": true },
    { "subtask": "Frontend auth UI", "estimated_tier": "SIMPLE", "can_parallelize": true }
  ],
  "historical_comparison": "Similar OAuth task took 3 iterations (Issue #45)",
  "integration_hints": {
    "github_artifact": "epic_with_sub_issues_and_project",
    "context_branch_budget": 16384,
    "worktree_recommended": true
  },
  "recommended_agents": {
    "always": ["code-quality-reviewer"],
    "if_go": [],
    "if_security_sensitive": ["security-reviewer", "vulnerability-reviewer"],
    "if_api_change": ["user-persona-reviewer", "documentation-reviewer"],
    "all": true
  },
  "intent_confirmation": {
    "required": true,
    "mode": "DETAILED"
  }
}

Integration

This skill is designed to be called by other commands/skills:

# In /brainstorm command Phase 2:

## Phase 2: Complexity Assessment (Context Folded)

mcp__contextd__branch_create(
  session_id: "<session>",
  description: "Assess task complexity",
  budget: 4096
)

1. Search contextd for similar past assessments
2. Apply 7-dimension analysis to user's task description
3. Calculate confidence score
4. Apply risk multipliers if applicable
5. Calculate tier based on adjusted score
6. Generate decomposition suggestions if COMPLEX
7. Record assessment in contextd with full JSON

mcp__contextd__branch_return(
  branch_id: "<branch>",
  message: JSON.stringify({
    tier: "<tier>",
    confidence: <0-100>,
    score: "<adjusted>/<max>",
    key_factors: ["<top 2 dimensions>"],
    decomposition: <if COMPLEX>,
    integration_hints: { github_artifact, context_branch_budget, worktree_recommended }
  })
)

Mandatory Checklist

EVERY assessment MUST complete ALL steps:

• Search contextd for similar past assessments (if available)
• Analyze Scope dimension with score and rationale
• Analyze Integration dimension with score and rationale
• Analyze Infrastructure dimension with score and rationale
• Analyze Knowledge dimension with score and rationale
• Analyze Risk dimension with score and rationale
• Analyze Testing dimension with score and rationale
• Analyze Decomposability dimension with score and rationale
• Calculate base score (sum of 7 dimensions)
• Apply risk multipliers if applicable
• Calculate confidence score with justification
• Determine tier from adjusted score
• Generate decomposition suggestions if COMPLEX
• Include integration hints (github-planning, context-folding)
• Include recommended_agents field based on tier and dimension scores
• Include intent_confirmation field (required + mode)
• Gate on intent confirmation (STANDARD: show plan; COMPLEX: require explicit "Yes")
• RECORD to contextd with full JSON (see Recording section)
• Return structured JSON output

The assessment is NOT complete until contextd recording is done.

Red Flags - STOP and Reconsider

If you're thinking any of these, you're about to violate the skill:

Common Mistakes

Tracking Assessment Accuracy

After task completion, update the original assessment:

mcp__contextd__memory_outcome(
  memory_id: "<original assessment id>",
  outcome: "success|partial|failure",
  notes: "Predicted STANDARD, actual was COMPLEX due to unexpected API rate limits"
)

Track metrics over time:

• Tier prediction accuracy
• Iteration count vs predicted
• Common underestimation patterns
• Team velocity calibration

Attribution

Adapted from Auto-Claude complexity_assessor.md by AndyMik90 (MIT). Enhanced with testing dimension, confidence scoring, decomposability analysis, and structured output. See CREDITS.md for full attribution.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.