Complexity Analyzer

Complexity Analysis Engine

Overview

Analyzes task and feature complexity using multiple factors to provide 1-10 scoring with actionable recommendations. This is a foundational skill used by other PopKit workflows.

Automatic integration: This skill is automatically invoked by planning workflows, PRD parsers, and agent routers. It operates silently in the background to provide complexity intelligence.

Complexity Scoring (1-10)

Complexity Factors

The analyzer evaluates 8 factors with configurable weights:

Usage Patterns

1. Automatic Analysis (Preferred)

Complexity analysis is automatically performed when you use development workflows:

/popkit:dev "Add user authentication"
# Automatically analyzes complexity
# Displays: "Analyzing complexity... Score: 7/10 (Complex)"
# Recommends: "5-7 subtasks suggested"
# Selects appropriate agents based on complexity

2. Explicit Analysis

/popkit:dev analyze "Refactor database layer"

3. From Skills (Python)

from popkit_shared.utils.complexity_scoring import analyze_complexity

# Analyze a task
result = analyze_complexity(
    "Add real-time notifications with WebSockets",
    metadata={
        "files_affected": 8,
        "dependencies": 5
    }
)

# Access results
score = result["complexity_score"]  # 7
subtasks = result["recommended_subtasks"]  # 6
phases = result["phase_distribution"]  # {"planning": 2, "implementation": 4, ...}
risks = result["risk_factors"]  # ["integration_complexity", "architecture_impact"]
agents = result["suggested_agents"]  # ["code-architect", "refactoring-expert"]

4. Integration with Skill Context

from popkit_shared.utils.skill_context import save_skill_context, SkillOutput
from popkit_shared.utils.complexity_scoring import analyze_complexity

# Analyze complexity
result = analyze_complexity(task_description)

# Save for downstream skills
save_skill_context(SkillOutput(
    skill_name="pop-complexity-analyzer",
    status="completed",
    output={
        "complexity_score": result["complexity_score"],
        "recommended_subtasks": result["recommended_subtasks"],
        "phase_distribution": result["phase_distribution"],
        "risk_factors": result["risk_factors"],
        "suggested_agents": result["suggested_agents"]
    },
    artifacts=[],
    next_suggested="pop-writing-plans"
))

Output Format

{
  "complexity_score": 7,
  "complexity_level": "COMPLEX",
  "recommended_subtasks": 6,
  "phase_distribution": {
    "discovery": 1,
    "planning": 2,
    "implementation": 4,
    "testing": 2,
    "review": 1,
    "integration": 1
  },
  "risk_factors": ["architecture_impact", "security_critical"],
  "reasoning": "Complexity Score: 7/10 (Architecture changes, high impact)...",
  "suggested_agents": ["code-architect", "refactoring-expert", "security-auditor"]
}

Integration Points

1. Agent Router

from popkit_shared.utils.complexity_scoring import quick_score

task = "Refactor authentication module"
complexity = quick_score(task)

if complexity >= 8:
    agent = "code-architect"  # Senior agent for complex tasks
elif complexity >= 5:
    agent = "refactoring-expert"
else:
    agent = "rapid-prototyper"

2. PRD Parser

features = parse_prd(document)
for feature in features:
    complexity = analyze_complexity(feature.description)
    feature.complexity_score = complexity["complexity_score"]
    feature.subtasks_recommended = complexity["recommended_subtasks"]

# Sort by complexity (tackle simple features first)
features.sort(key=lambda f: f.complexity_score)

3. Planning Workflows

complexity_result = analyze_complexity(task_description)
score = complexity_result["complexity_score"]

if score <= 4:
    workflow = "quick_mode"  # 5 steps
elif score <= 7:
    workflow = "standard_mode"  # 7 phases
else:
    workflow = "full_mode_with_architecture"

Subtask Recommendations

Phase Distribution

Trivial (1-2): Implementation: 1, Testing: 1

Simple (3-4): Planning: 1, Implementation: 2, Testing: 1

Moderate (5-6): Planning: 1, Implementation: 3, Testing: 2, Review: 1

Complex (7-8): Discovery: 1, Planning: 2, Implementation: 4, Testing: 2, Review: 1, Integration: 1

Very Complex (9-10): Discovery: 2, Architecture: 2, Planning: 3, Implementation: 5, Testing: 3, Review: 2, Integration: 2, Documentation: 1

Risk Factor Detection

Agent Recommendations

Keyword Detection

Architecture: architecture, refactor, redesign, restructure, migrate Breaking Changes: breaking, incompatible, migration, deprecated Security: auth, authentication, authorization, security, crypto, encryption Integration: integrate, api, webhook, third-party, external Database: database, schema, migration, query, index Testing: e2e, integration test, test coverage, regression

Best Practices

1. Automatic by Default: Let workflows invoke complexity analysis automatically
2. Trust the Score: Complexity scores are calibrated for accuracy
3. Use Recommendations: Follow subtask and phase recommendations
4. Monitor Risks: Pay attention to identified risk factors
5. Right-Size Agents: Use suggested agents for better results
6. Iterate if Needed: Re-analyze after scope changes

Related Skills

• pop-writing-plans - Uses complexity for plan generation
• pop-brainstorming - Uses complexity to determine depth
• pop-executing-plans - Uses complexity for batch sizing

Related Commands

• /popkit:dev - Automatic complexity analysis
• /popkit:issue - Complexity-based prioritization
• /popkit:milestone - Aggregate complexity reporting