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)

Score	Level	Description	Example
1-2	Trivial	Single file, minimal changes	Fix typo, update constant
3-4	Simple	Few files, straightforward logic	Add button, update styling
5-6	Moderate	Multiple files, some complexity	Add form validation, API endpoint
7-8	Complex	Architecture changes, high impact	Refactor module, add auth system
9-10	Very Complex	System-wide changes, high risk	Migrate architecture, redesign core

Complexity Factors

The analyzer evaluates 8 factors with configurable weights:

Factor	Weight	Description
Files Affected	15%	Number of files that need changes
LOC Estimate	15%	Estimated lines of code
Dependencies	15%	External/internal dependencies
Architecture Change	20%	Impact on system architecture
Breaking Changes	15%	Compatibility impact
Testing Complexity	10%	Testing requirements
Security Impact	5%	Security considerations
Integration Points	5%	External integrations

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

Complexity	Subtasks	Strategy
1-2	1	Single task
3-4	2-3	Simple breakdown
5-6	3-5	Moderate breakdown
7-8	5-7	Detailed breakdown
9-10	8-12	Extensive breakdown

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

Risk Factor	Trigger	Impact
breaking_changes	Breaking change keywords	Compatibility issues
security_critical	Auth/security keywords	Security review needed
architecture_impact	Architecture keywords	Design review required
integration_complexity	Integration keywords	External coordination
performance_sensitive	Performance keywords	Performance testing
data_migration	Migration keywords	Data safety concerns

Agent Recommendations

Complexity	Suggested Agents
1-3	rapid-prototyper, code-explorer
4-6	refactoring-expert, code-explorer, test-writer
7-8	code-architect, refactoring-expert, security-auditor
9-10	code-architect, system-designer, tech-lead, security-auditor

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