From 0af2f200d812688829ac1bb15e8cbc87e42cf14e Mon Sep 17 00:00:00 2001 From: kami Date: Tue, 21 Jul 2026 02:05:20 +0400 Subject: [PATCH] fix(prompts): resolve analyst epic-vs-child ambiguity that burned the full reasoning budget (#297) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Live incident: "Write a web-ui for Correx" resolved to a pre-existing parent epic (webui-8, with children webui-9..14). The old prompt only said "name a task that covers this work" and, separately, "after decomposing, name the single ready child" — it never said what to do when an EXISTING task found via task_search/task_context is itself a parent. The model oscillated between naming the epic, re-decomposing, or working a child until it burned all 16384 reasoning tokens and emitted nothing. Reworded analyst_freestyle.md's task-framing section so every branch (existing leaf, existing parent, no task yet + single unit, no task yet + needs decomposition) converges on one rule: never name a parent/epic, always name the single ready child — removing the decision entirely rather than asking the model to make it under ambiguity. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01GeyGFXczJb8RUWGBKmkm6G --- .../workflows/prompts/analyst_freestyle.md | 31 +++++++++++++------ 1 file changed, 21 insertions(+), 10 deletions(-) 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.