Complexity Assessment Skill Overview Analyze a task description and determine its true complexity to ensure the right workflow and validation depth are selected. Accuracy over speed - wrong complexity means wrong workflow means failed implementation. Core principle: Accuracy over speed. Wrong complexity = wrong workflow = failed implementation. When to Use Always: Before planning any new task When requirements are gathered but approach unclear When determining validation depth for QA Exceptions: Obvious simple fixes (typos, color changes) Tasks where complexity is explicitly specified Iron Laws NEVER begin planning without complexity assessment — wrong complexity tier = wrong workflow = failed implementation; always assess first, then select the appropriate workflow phases and validation depth. ALWAYS be conservative when uncertain — go higher — underestimating complexity is more dangerous than overestimating; a COMPLEX task mis-classified as STANDARD skips security review, architecture design, and comprehensive testing. ALWAYS count affected files before assigning a tier — gut-feel estimates are unreliable; scan the codebase to count files actually touched by the change before assigning SIMPLE/STANDARD/COMPLEX/EPIC. ALWAYS flag unfamiliar technologies for research — unknown tech has hidden complexity; mark any unfamiliar framework, library, or service as requiring research before proceeding with the complexity estimate. NEVER let the user's casual language lower the tier — "just a quick fix" or "small change" reflects the user's perception, not the actual technical scope; assess objectively regardless of how it is described. Workflow Types Determine the type of work being requested: FEATURE Adding new functionality to the codebase Enhancing existing features with new capabilities Building new UI components, API endpoints, or services Examples: "Add screenshot paste", "Build user dashboard", "Create new API endpoint" REFACTOR Replacing existing functionality with a new implementation Migrating from one system/pattern to another Reorganizing code structure while preserving behavior Examples: "Migrate auth from sessions to JWT", "Refactor cache layer" INVESTIGATION Debugging unknown issues Root cause analysis for bugs Performance investigations Examples: "Find why page loads slowly", "Debug intermittent crash" MIGRATION Data migrations between systems Database schema changes with data transformation Import/export operations Examples: "Migrate user data to new schema", "Import legacy records" SIMPLE Very small, well-defined changes Single file modifications No architectural decisions needed Examples: "Fix typo", "Update button color", "Change error message" Complexity Tiers SIMPLE 1-2 files modified Single service/area No external integrations No infrastructure changes No new dependencies Examples: typo fixes, color changes, text updates, simple bug fixes STANDARD 3-10 files modified 1-2 services/areas 0-1 external integrations (well-documented, simple to use) Minimal infrastructure changes (e.g., adding an env var) May need some research but core patterns exist Examples: adding a new API endpoint, creating a new component COMPLEX 10+ files OR cross-cutting changes Multiple services/areas 2+ external integrations Infrastructure changes (Docker, databases, queues) New architectural patterns Greenfield features requiring research Examples: new integrations (Stripe, Auth0), database migrations, new services Workflow Phase 1: Load Requirements Read the requirements document:

Read the requirements file

cat

.claude/context/requirements/

[

task-name

]

.md

Extract:

task_description

What needs to be built

workflow_type

Type of work (feature, refactor, etc.)

scope

Which areas are affected

requirements

Specific requirements

acceptance_criteria

How success is measured

constraints

Any limitations Phase 2: Analyze the Task Read the task description carefully. Look for: Complexity Indicators (suggest higher complexity): "integrate", "integration" - external dependency "optional", "configurable", "toggle" - feature flags, conditional logic "docker", "compose", "container" - infrastructure Database names (postgres, redis, mongo) - infrastructure + config API/SDK names (stripe, auth0, openai) - external research needed "migrate", "migration" - data/schema changes "across", "all services", "everywhere" - cross-cutting "new service" - significant scope ".env", "environment", "config" - configuration complexity Simplicity Indicators (suggest lower complexity): "fix", "typo", "update", "change" - modification "single file", "one component" - limited scope "style", "color", "text", "label" - UI tweaks Specific file paths mentioned - known scope Phase 3: Assess Dimensions Scope Analysis How many files will likely be touched? How many areas are involved? Is this a localized change or cross-cutting? Integration Analysis Does this involve external services/APIs? Are there new dependencies to add? Do these dependencies require research? Infrastructure Analysis Does this require Docker/container changes? Does this require database schema changes? Does this require new environment configuration? Knowledge Analysis Does the codebase already have patterns for this? Will research be needed for external docs? Are there unfamiliar technologies involved? Risk Analysis What could go wrong? Are there security considerations? Could this break existing functionality? Phase 4: Determine Phases Needed Based on your analysis, determine which phases are needed: For SIMPLE tasks: discovery → quick_spec → validation (3 phases, no research, minimal planning) For STANDARD tasks: discovery → requirements → context → spec_writing → planning → validation (6 phases, context-based spec writing) For STANDARD tasks WITH external dependencies: discovery → requirements → research → context → spec_writing → planning → validation (7 phases, includes research for unfamiliar dependencies) For COMPLEX tasks: discovery → requirements → research → context → spec_writing → self_critique → planning → validation (8 phases, full pipeline with research and self-critique) Phase 5: Determine Validation Depth Based on complexity and risk analysis, recommend validation depth: Risk Level When to Use Validation Depth TRIVIAL Docs-only, comments, whitespace Skip validation entirely LOW Single area, < 5 files, no DB/API changes Unit tests only MEDIUM Multiple files, 1-2 areas, API changes Unit + Integration tests HIGH Database changes, auth/security, cross-service Unit + Integration + E2E + Security CRITICAL Payments, data deletion, security-critical All above + Manual review + Staging Skip Validation Criteria (TRIVIAL): Set only when ALL are true: Documentation-only changes (*.md, comments, docstrings) OR purely cosmetic (whitespace, formatting, linting fixes) No functional code modified Confidence >= 0.9 Security Scan Required when ANY apply: Authentication/authorization code touched User data handling modified Payment/financial code involved API keys, secrets, or credentials handled New dependencies with network access File upload/download functionality Phase 6: Output Assessment Create the structured assessment:

Complexity Assessment: [Task Name]

Summary | Dimension | Assessment | |

|

| | Complexity | [simple/standard/complex] | | Workflow Type | [feature/refactor/investigation/migration/simple] | | Confidence | [0.0-1.0] |

Reasoning [2-3 sentence explanation]

Analysis

Scope

Estimated files: [number]

Estimated areas: [number]

Cross-cutting: [yes/no]

Notes: [brief explanation]

Integrations

External services: [list]

New dependencies: [list]

Research needed: [yes/no]

Notes: [brief explanation]

Infrastructure

Docker changes: [yes/no]

Database changes: [yes/no]

Config changes: [yes/no]

Notes: [brief explanation]

Knowledge

Patterns exist: [yes/no]

Research required: [yes/no]

Unfamiliar tech: [list]

Notes: [brief explanation]

Risk

Level: [low/medium/high]

Concerns: [list]

Notes: [brief explanation]

Recommended Phases 1. [phase1] 2. [phase2] 3. ...

Validation Recommendations | Setting | Value | |

|

|

|

Risk Level

|

[trivial/low/medium/high/critical]

|

|

Skip Validation

|

[yes/no]

|

|

Minimal Mode

|

[yes/no]

|

|

Test Types

|

[unit, integration, e2e]

|

|

Security Scan

|

[yes/no]

|

|

Staging Required

|

[yes/no]

|

**

Reasoning

**

[1-2 sentences explaining validation depth]

Flags

Needs research: [yes/no]

Needs self-critique: [yes/no]

Needs infrastructure setup: [yes/no]

Decision Flowchart

START

|

+--> Are there 2+ external integrations OR unfamiliar technologies?

| YES -> COMPLEX (needs research + critique)

| NO

| |

+--> Are there infrastructure changes (Docker, DB, new services)?

| YES -> COMPLEX (needs research + critique)

| NO

| |

+--> Is there 1 external integration that needs research?

| YES -> STANDARD + research phase

| NO

| |

+--> Will this touch 3+ files across 1-2 areas?

| YES -> STANDARD

| NO

| |

+--> SIMPLE (1-2 files, single area, no integrations)

Verification Checklist

Before completing assessment:

Requirements document read completely

All complexity indicators identified

All simplicity indicators identified

Scope analyzed (files, areas, cross-cutting)

Integrations analyzed (external, dependencies)

Infrastructure needs assessed

Knowledge gaps identified

Risk level determined

Phases determined

Validation depth recommended

Common Mistakes

Underestimating Integrations

Why it's wrong:

One integration can touch many files.

Do this instead:

Flag research needs for any unfamiliar technology.

Ignoring Infrastructure

Why it's wrong:

Docker/DB changes add significant complexity.

Do this instead:

Check for infrastructure needs early.

Over-Confident

Why it's wrong:

Rarely should confidence be above 0.9.

Do this instead:

Be conservative. When in doubt, go higher complexity.

Integration with Other Skills

This skill works well with:

spec-gathering

Provides requirements for assessment

spec-writing

Uses assessment to determine spec depth

qa-workflow

Uses validation recommendations Anti-Patterns Anti-Pattern Why It Fails Correct Approach Assigning SIMPLE without file scan Underestimates actual affected file count Count affected files before assigning tier "Quick fix" language lowers tier User perception ≠ technical scope Assess objectively; ignore casual user framing Ignoring integrations and external APIs External dependencies add risk and complexity List all external services/APIs in the assessment Skipping research flag for unknown tech Unfamiliar tech has invisible complexity Flag any unfamiliar technology for research Not considering rollback complexity COMPLEX/EPIC need recovery plans Include rollback difficulty in complexity scoring Memory Protocol Before starting: Read .claude/context/memory/learnings.md After completing: New pattern -> .claude/context/memory/learnings.md Issue found -> .claude/context/memory/issues.md Decision made -> .claude/context/memory/decisions.md ASSUME INTERRUPTION: If it's not in memory, it didn't happen.