planning-decomposition-quality

name	planning-decomposition-quality
description	Break architecture into execution-ready sub-tasks with clear ownership, dependencies, and contract references. Use this when acting as the planner for a task.
owner	planner
trigger	null
version	1

Planning Decomposition Quality

Use this before finalizing a task plan.

Goal

Produce a plan that is executable by specialist agents without re-planning the architecture or creating avoidable coordination conflicts.

Checklist

1. Make sub-tasks ownership-clean. Each sub-task should have one primary agent and a file set that is as non-overlapping as possible.
2. Put prerequisites first. Shared types, scaffolding, migrations, base contracts, and other enabling work should land before dependent tasks.
3. Reference contracts explicitly. Each sub-task should name the API contracts, data models, or shared types it implements or consumes.
4. Keep tasks independently completable. A good sub-task has a bounded output, a clear file surface, and a verification path. Avoid giant mixed concerns.
5. Keep dependencies minimal but real. Only add a dependency when ordering truly matters. Missing dependencies create breakage; excess dependencies create unnecessary serialization.
6. Decompose around stable seams, not maximal fanout. Prefer a few boundary-centered tasks over many tiny slices. Good seams are shared types/contracts, runtime loop/integration, UI surface, persistence boundary, or verification/hardening.
7. Avoid recursive planning language. Execution agents should read planning docs and build code, not restate or redesign the architecture.
8. Make browser-facing work browser-verifiable. For frontend, Phaser, canvas, page, HUD, menu, or dashboard work, describe the visible user outcome QA should exercise, not just the files to edit.

Guardrails

• Do not assign the same file to multiple agents unless there is a strong reason and the overlap is clearly explained.
• Do not create "cleanup later" tasks for problems that should be fixed in the owning task.
• Do not omit shared-types or setup work when later tasks depend on it.
• If the repo structure is unclear, activate new-file-placement before locking file paths.
• Do not use vague browser-facing titles like Polish UI or Update game scene; name the surface and the visible result QA should check.
• Avoid plans deeper than about 4 dependency layers; if the graph is getting tall, combine work by boundary instead of stacking more prerequisites.
• For broad plans, most sub-tasks should include explicit Files: or Contracts: scope. A long list of vague tasks with neither is a sign the decomposition is not execution-ready.

Deliverable Standard

Before submitting, ask:

• Could each sub-task be handed to a single execution agent and started immediately?
• Would the dependency graph prevent obvious race conditions or missing prerequisites?
• Does every task point back to the architecture contracts it must honor?

If not, tighten the decomposition before calling submit_deliverable.