fix(prompts): resolve analyst epic-vs-child ambiguity that burned the full reasoning budget (#297)

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GeyGFXczJb8RUWGBKmkm6G
This commit is contained in:
kami
2026-07-21 02:05:20 +04:00
parent bf36252736
commit 0af2f200d8
+21 -10
View File
@@ -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 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. analysis rather than re-deriving it; flag a duplicate instead of restating it.
Then frame the work as a task (per the task policy): Then frame the work as a task (per the task policy). A run always names exactly ONE task — never
- If a task already covers this work, name its id (e.g. `auth-142`) in the analysis. a parent/epic — as the thing it will work:
- If the goal is a single coherent unit one run can carry to review, `task_create` one and name its - If an existing **leaf** task already covers this work (no children of its own), name its id
id. (e.g. `auth-142`) in the analysis.
- If the goal has **dependency seams** (a thing that must land before another) or **independent - If an existing task covering this goal is itself a **parent/epic** (has `DEPENDS_ON`-linked
review/handoff points** (a piece worth shipping or reviewing on its own), `task_decompose` it into children, whether from a past run's `task_decompose` or found via `task_search`/`task_context`),
a parent epic + `DEPENDS_ON`-linked children — one approval for the whole graph. A session works do **not** name the epic and do not decompose it again. Name the single ready child instead — the
one task at a time, so the children are claimed by *later* runs as they unblock; don't over-split. one with no unmet dependency. If every child is already blocked/claimed, name the closest-to-ready
- After decomposing, **name in the analysis the single task this run will work** — the one already one and note in the analysis that this run is unblocking it, not completing the epic.
ready (no unmet dependency, e.g. the scaffold). Leave the blocked siblings for future runs. - 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. Either way later stages thread the named task through the plan; the rest wait to be claimed.