diff --git a/examples/workflows/prompts/analyst_freestyle.md b/examples/workflows/prompts/analyst_freestyle.md index 603eb5df..9da09876 100644 --- a/examples/workflows/prompts/analyst_freestyle.md +++ b/examples/workflows/prompts/analyst_freestyle.md @@ -6,16 +6,27 @@ Before deriving requirements, check for existing work: `task_search` for related blocking tasks and `task_context` to load any the goal names. Fold what you find into the analysis rather than re-deriving it; flag a duplicate instead of restating it. -Then frame the work as a task (per the task policy): -- If a task already covers this work, name its id (e.g. `auth-142`) in the analysis. -- If the goal is a single coherent unit one run can carry to review, `task_create` one and name its - id. -- If the goal has **dependency seams** (a thing that must land before another) or **independent - review/handoff points** (a piece worth shipping or reviewing on its own), `task_decompose` it into - a parent epic + `DEPENDS_ON`-linked children — one approval for the whole graph. A session works - one task at a time, so the children are claimed by *later* runs as they unblock; don't over-split. -- After decomposing, **name in the analysis the single task this run will work** — the one already - ready (no unmet dependency, e.g. the scaffold). Leave the blocked siblings for future runs. +Then frame the work as a task (per the task policy). A run always names exactly ONE task — never +a parent/epic — as the thing it will work: +- If an existing **leaf** task already covers this work (no children of its own), name its id + (e.g. `auth-142`) in the analysis. +- If an existing task covering this goal is itself a **parent/epic** (has `DEPENDS_ON`-linked + children, whether from a past run's `task_decompose` or found via `task_search`/`task_context`), + do **not** name the epic and do not decompose it again. Name the single ready child instead — the + one with no unmet dependency. If every child is already blocked/claimed, name the closest-to-ready + one and note in the analysis that this run is unblocking it, not completing the epic. +- If no task covers this work yet and the goal is a single coherent unit one run can carry to + review, `task_create` one and name its id. +- If no task covers this work yet and the goal has **dependency seams** (a thing that must land + before another) or **independent review/handoff points** (a piece worth shipping or reviewing on + its own), `task_decompose` it into a parent epic + `DEPENDS_ON`-linked children — one approval for + the whole graph. A session works one task at a time, so the children are claimed by *later* runs + as they unblock; don't over-split. Then name the single ready child (the one already unblocked, + e.g. the scaffold) — never the epic itself. + +There is always exactly one task id to name by the time you call `emit_artifact` — if you find +yourself unsure whether to name a parent or a child, the answer is always the child. Do not loop on +this decision. Either way later stages thread the named task through the plan; the rest wait to be claimed.