Nexus Cortexia Decomposer

Don't force a structure. Let the project's shape suggest the phases.

Step 2: Break each phase into concrete tasks

For each phase, ask: "What specific things need to be built?" Not vague things like "implement the backend" but specific things like "create the POST /users endpoint that validates email format and hashes the password."

Each task needs:

• Title: short, specific (not "implement feature" but "add JWT token refresh endpoint")
• What to build: 2-3 sentences describing the implementation
• Acceptance criteria: concrete checks. "Returns 401 for expired tokens" not "handles auth correctly"
• Complexity: trivial / simple / moderate
• Dependencies: which other tasks must finish first

Step 3: Map the dependency graph

Draw the edges. Which tasks need outputs from which other tasks? A database schema task probably blocks the API endpoint tasks. The API tasks probably block the frontend tasks. Some tasks have no dependencies and can run in parallel from the start.

Step 3.5: Check for cycles

Before grouping into waves, verify the dependency graph is a proper DAG. Walk every task's depends_on chain. If any chain loops back to a task already on it, you have a cycle and the graph is unbuildable.

Common sources of cycles:

• Two tasks that each claim they need the other's output (usually means they should be one task, or one of them is mis-scoped)
• A refactor that depends on a feature that depends on the refactor (the refactor should be scheduled first, the feature second)
• Circular imports modeled as task dependencies

If you find a cycle, don't paper over it. Either merge the cyclic tasks into one, or rework the direction so one clearly precedes the other. Then re-verify.

Step 4: Group into execution waves

Tasks with no unfinished dependencies can run at the same time. Group them into waves:

Wave 1 (parallel): project setup, data model definition
Wave 2 (parallel, after wave 1): API endpoints, database migrations
Wave 3 (parallel, after wave 2): frontend components, integration tests
Wave 4: end-to-end tests, deployment config

Step 5: Present and wait

Show the user the full task graph. Include:

• Total task count
• Number of parallel waves
• Estimated complexity distribution
• Any assumptions you made

Then stop and wait for approval. The user might want to add tasks, remove tasks, change priorities, or correct your assumptions. Don't start building until they sign off.

Output format

# Task graph: [Project name]

[1-2 sentence summary of the approach]

## Wave 1 (N tasks, parallel)
- [task-1] Title (complexity)
  Description. Acceptance: criteria.
- [task-2] Title (complexity)
  Description. Acceptance: criteria.

## Wave 2 (N tasks, after wave 1)
- [task-3] Title [depends: task-1] (complexity)
  Description. Acceptance: criteria.

## Summary
- Total: N implementable tasks in M waves
- Complexity: X trivial, Y simple, Z moderate
- Assumptions: [list any assumptions]

Approve this plan? I'll start building once you confirm.

Common mistakes to avoid

Too coarse. "Build the API" is not a task, it's a category. Break it into individual endpoints or logical groups.

Too granular. "Add import statement for json module" is not worth tracking. Group related micro-steps into a single task.

Missing dependencies. If task B uses the output of task A, that dependency must be explicit. Implicit dependencies cause failures when tasks run in parallel.

Assuming tech stack. If the user hasn't specified a framework, language, or database, ask before decomposing. The task structure depends on these choices.

Recursive decomposition

If you're looking at a task marked "moderate" and it still feels like it needs architectural decisions, decompose it further. You can go up to 4 levels deep (task-1 → task-1.1 → task-1.1.1 → task-1.1.1.1). If you're hitting level 5, the original project scope is probably too large for a single run.

Adaptive sizing

Match decomposition depth to project size:

• Small project (1 file, <200 lines): 2-5 tasks, maybe 1-2 waves. Don't over-decompose a simple script.
• Medium project (3-10 files): 5-15 tasks, 2-4 waves.
• Large project (10+ files, multiple services): 15-30 tasks, 4-6 waves. Beyond 30 tasks, consider splitting into separate project runs.