plan-decomposition

name	plan-decomposition
description	Use when a user asks to break a goal into tasks, decompose a feature, or plan a sequence of agent work

Plan Decomposition

Overview

Praetor plans are dependency graphs of small task prompts. Decompose goals into tasks that one implementer agent can complete in one session, with a binary verification command per task.

Announce at start: "I'm using the plan-decomposition skill to break the goal into Praetor tasks."

When to Use

Use this skill when the user asks to:

• break a goal into tasks
• decompose a feature
• plan a sequence of agent work
• create a queue where multiple agents may eventually run independent work

After decomposition, use task-authoring to write each task file.

Dependency Analysis

Before writing files, identify what must happen before what.

Ask these questions:

• Does task B need code, tests, generated files, or decisions from task A?
• Does task B depend on an API shape, schema, CLI flag, migration, fixture, or contract introduced by task A?
• Would running task B first cause rework or guesswork?
• Can task B be verified without task A being complete?

If the answer is yes, B must list A in depends_on.

Typical dependency shapes:

• Linear: schema before parser before CLI.
• Fan-out: shared interface first, then independent implementations.
• Fan-in: independent pieces first, then integration or docs.
• Diamond: foundation, parallel siblings, final end-to-end task.

Parallel Grouping

Set parallel_ok: true only for tasks that are safe to run at the same time as other ready sibling tasks.

Good parallel candidates:

• tests for separate modules after a shared interface exists
• independent adapters behind a locked protocol
• docs and focused tests that touch different files
• UI panels that do not share layout or state files

Keep parallel_ok: false when:

• tasks edit the same files or nearby code paths
• one task needs decisions discovered by another
• the task performs migrations, broad refactors, or cross-cutting formatting
• the verify command mutates shared state or requires exclusive resources

Praetor runs sequentially by default. When the user runs with --max-parallel > 1, ready tasks with parallel_ok: true may run concurrently in worktrees; parallel_ok: false tasks run alone.

Merge Strategy

For most decomposition outputs, leave the default merge_strategy: manual so the user reviews each task before integration.

Suggest merge_strategy: auto only when all of these are true:

• the task has a verify command
• the task scope is genuinely isolated, such as a single file or single module
• the task is unlikely to overlap with sibling tasks
• the user has explicitly indicated comfort with auto-merging

Writing the DAG

Represent the graph directly in each task's frontmatter:

depends_on: []

or:

depends_on: [001-foundation, 003-unit-tests]

Rules:

• Dependencies point backward to prerequisite task ids.
• Do not list downstream tasks.
• Do not create cycles.
• Do not use status: ready; use status: pending and let Praetor derive readiness.
• The filename must match id: .praetor/tasks/<id>.md.

Task Sizing

Each task should fit one focused agent session.

A good task has:

• one clear behavioral outcome
• a small set of files to inspect or modify
• enough context to avoid guessing
• a binary verify command
• proof expectations that a reviewer can check

Split a task when:

• it says "also"
• the verify command is a whole-repo command but the work is only partly related
• the agent must design an interface and implement several consumers
• success requires both implementation and broad documentation or migration work

Merge tasks when:

• neither task can be verified alone
• they would edit the same tiny file in contradictory ways
• one task is only mechanical setup for the next and has no independent proof

Worked Example

Goal: add a retry policy for failed Praetor tasks.

Decomposition:

• 001-add-retry-schema defines the task/state fields and tests parsing.
• 002-render-retry-status updates status output after the schema exists.
• 003-runner-retries-failed-tasks implements retry behavior after the schema exists.
• 004-retry-e2e verifies the CLI flow after status and runner behavior exist.

Task files:

---
id: 001-add-retry-schema
status: pending
depends_on: []
parallel_ok: false
agent: claude
verify: pytest tests/unit/test_models.py tests/unit/test_frontmatter.py
merge_strategy: manual
created: 2026-06-07T19:00:00Z
review: off
---

# Add retry schema

## What to do

Add retry metadata to Praetor task parsing and serialization. Inspect `praetor/models.py` and `praetor/frontmatter.py`. Preserve round-trip behavior for existing task files.

## How to verify

Run `pytest tests/unit/test_models.py tests/unit/test_frontmatter.py`. The command must exit 0 and include coverage for default retry values and explicit frontmatter values.

## Proof when complete

Report the passing pytest output and the exact frontmatter fields added.

---
id: 002-render-retry-status
status: pending
depends_on: [001-add-retry-schema]
parallel_ok: true
agent: claude
verify: pytest tests/unit/test_status_command.py
merge_strategy: manual
created: 2026-06-07T19:05:00Z
review: off
---

# Render retry status

## What to do

Update the status command to show retry count for tasks that have retry metadata. Keep output unchanged for tasks without retries.

## How to verify

Run `pytest tests/unit/test_status_command.py`. The command must exit 0 and cover tasks with and without retry metadata.

## Proof when complete

Report the passing pytest output and one sample status line.

---
id: 003-runner-retries-failed-tasks
status: pending
depends_on: [001-add-retry-schema]
parallel_ok: false
agent: claude
verify: pytest tests/unit/test_runner.py
merge_strategy: manual
created: 2026-06-07T19:10:00Z
review: strict
---

# Retry failed tasks in the runner

## What to do

Update the sequential runner so a failed task is retried while retries remain, then marked `failed` only after the final failed attempt. Keep downstream blocked propagation unchanged after final failure.

## How to verify

Run `pytest tests/unit/test_runner.py`. The command must exit 0 and include a case where the second attempt succeeds and a case where retries are exhausted.

## Proof when complete

Report the passing pytest output and summarize the status transitions for both retry cases.

---
id: 004-retry-e2e
status: pending
depends_on: [002-render-retry-status, 003-runner-retries-failed-tasks]
parallel_ok: false
agent: claude
verify: pytest tests/e2e/test_retry_policy.py
merge_strategy: manual
created: 2026-06-07T19:15:00Z
review: strict
---

# Add retry policy e2e coverage

## What to do

Add an end-to-end test that initializes a scratch Praetor workspace, creates a task with retry metadata, runs the queue, and verifies retry behavior plus status output.

## How to verify

Run `pytest tests/e2e/test_retry_policy.py`. The command must exit 0 and fail if retry execution or retry status rendering is broken.

## Proof when complete

Report the passing pytest output and the final task statuses from the e2e fixture.

Why this DAG works:

• 001 is first because schema controls all later task files and code paths.
• 002 and 003 both depend on 001; they can be developed independently after the schema exists, but only 002 is marked parallel-safe because 003 changes shared runner behavior.
• 004 depends on both implementation branches because it verifies the integrated workflow.

Pitfalls

• Circular dependencies: if A depends on B and B depends on A, neither can run. Break the cycle by extracting a smaller foundation task.
• Tasks too large: if a task spans schema, runner, CLI, docs, and e2e, split it into foundation, implementation, and integration tasks.
• Verify commands too broad: pytest for a focused CLI display task gives weak proof and slow feedback. Prefer the narrow test file that proves the task.
• Hidden dependencies: if a task needs an interface, fixture, migration, or decision from another task, put that task id in depends_on.
• Unsafe parallelism: do not set parallel_ok: true for siblings that edit the same files or make competing design decisions.