complexity-assessment
AI-based complexity assessment for task analysis. Use when determining the appropriate workflow, phases, and validation depth for a task.
How do I install this agent skill?
npx skills add https://github.com/oimiragieo/agent-studio --skill complexity-assessmentIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a structured methodology for assessing task complexity and identifying security-critical operations for further review. No malicious patterns were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/oimiragieo/agent-studio/complexity-assessment">View complexity-assessment on skillZs</a>