Module 3 · Planning, Context & Multi-agent Systems · scripted

Task Decomposition: Trees with Evidence

35 minoutcomes: multi-agent, agent-architectures

The promised lesson

We've been circling this one since the touch points: choosing where trajectories meet is the decomposition problem, and it was promised its own treatment. Here it is — the multi-conversation archetype where the object of design is not the roles but the task itself: how to break one goal into subtasks that separate conversations can complete, such that the pieces provably come back together.

What we are optimizing

Break the task into subtasks that are:

  INDEPENDENT   each completable without conversing with the
                others — its brief is enough
  COMPOSABLE    the outputs fit together by design — declared
                interfaces, not hopeful prose
  EVIDENCED     "complete" means evidence, not assertion

Independence buys PARALLELISM and FAILURE ISOLATION.
Composability buys a whole from the parts.
Evidence buys knowing which subtree to distrust.

The tree

Decomposition produces a tree: the goal at the root, subtasks as children, recursively, down to leaves small enough for one clean conversation. The map first:

One goal, one tree

Two properties of this picture do all the work. Siblings are parallel: A, B, C run as three simultaneous conversations — three walls, three clean trajectories, finished in the time of the slowest, not the sum. And failures stay in their subtree: if A1 goes wrong, the damage is bounded by A — B's and C's conversations never saw A1, so they cannot have been conditioned by its mistakes. The tree is the firebreak diagram, drawn before any conversation starts.

But both properties hold only if the cuts were real — and cuts are real only if the seams were declared:

The seam contract, per edge of the tree

For every parent–child edge:
BRIEF INwhat the child needs — small, bounded, self-contained (the child asks no questions)
DELIVERABLEwhat comes back — named, typed, addressed
INTERFACEwhat OTHER subtrees may rely on — declared up front, frozen: "A2 exposes get_readings(sensor, range) returning UTC rows in meters"

B2 is built against A2's DECLARED interface — never against A2's conversation. If B2 needs to know how A2 went about its work, the decomposition has failed before it began.

Evidence of correctness

Now the part that turns decomposition from hopeful management into engineering. Every subtask's definition includes one more field: what evidence will show it is actually done? Not "the conversation said so" — every trajectory believes in its own work. Evidence, and it comes in two strengths:

Hard and soft evidence

HARDthe world confirms it — code checks, exact: the adapter compiles and its test suite passes run ingest(sample-file) → returns 4,112 rows, 0 rejects the portal URL answers 200 and serves the map tile get_readings("B2-07", week) returns UTC/meters — checked by a script against the declared interface
SOFTa judge confirms it — one fresh thought: "Here is the documentation site and the three user tasks it must support. Score each 1–5 for whether a newcomer could complete it." — critic scores 5,4,5 "Does this API-client code follow the declared interface, including error cases?" — critic agrees

Prefer hard where hard exists. Where quality is the deliverable — prose, design, explanation — soft evidence is real evidence: a critic with fresh eyes and a stated bar, not the builder grading itself.

Example 1 · A leaf closes with evidence
user

[subtask A1 brief:] Build the NTNU feed adapter to interface A2-v1 (attached). Definition of done: adapter passes the conformance script check_a1.sh against the three sample files; all rows delivered in UTC/meters.

assistant
⟨tool_use⟩
run_command(cmd = "./check_a1.sh samples/")
user
⟨tool_result⟩
3/3 files: PASS. 4,112 rows, 0 rejects, schema conformant,
timezone/unit checks green.
assistant

A1 complete. Evidence: conformance script green on all three samples — [log e-41 attached]. Deliverable: adapter at adapters/ntnu.py, built against A2-v1.

NoteThe leaf doesn't report "I finished" — it reports evidence e-41. The parent never re-reads A1's conversation to trust it; it reads the log. Completion claims travel as evidence, and evidence is small: the whole subtree collapses to one line and one handle, exactly what the parent's wall wants to carry.

When composition fails anyway

Independence is a bet — the same bet every cut makes — and the place bets fail is at the joints. So the tree has one more rule: composition is itself a task, with its own evidence. When siblings' deliverables meet, something must check the fit:

Example 2 · The joint test catches a drift
user

[integration task, after A and B complete:] Compose: front-end B against ingestion A. Run the joint evidence: check_join.sh — end-to-end: ingest sample → query via portal → verify plotted values match source.

assistant
⟨tool_use⟩
run_command(cmd = "./check_join.sh")
user
⟨tool_result⟩
FAIL: map view shows depths 5.5× too large for 12 of 12 test
points. A2 serves meters (per interface). B1 plots values with
label "depth (m)" but axis scaled as if fathoms→meters were
still needed.
assistant

The joint evidence localizes this precisely: A2's output conforms to its declared interface (its own evidence is green), so the defect is in B1's use of it — B1 double-converted. Reopening B1 only; A's subtree stays closed. Brief for B1: "your conformance evidence passed because your unit test used raw fathom fixtures — update fixtures to A2-v1 output and remove the conversion."

NoteThis is the payoff of the whole architecture. Because every subtree carried evidence, the failure localizes: A proved conformance, so suspicion falls on one leaf — not on everything. One conversation reopens; five stay closed. Without evidence, a composition failure means re-distrusting the entire tree — which is re-doing it.

The decomposition laws

1. Cut where the seam is thin — small brief, small
   deliverable, declared interface.
2. Siblings must not need each other's conversations —
   independence is what parallelism and isolation are
   made of.
3. Every subtask closes with EVIDENCE — hard where the
   world can testify, soft (a fresh critic against a
   stated bar) where it can't.
4. Every joint is a task: composition gets its own
   evidence.
5. When a joint fails, evidence localizes the fault —
   reopen the guilty subtree, not the tree.

What "done" means at the root

Climb back to the root and notice what the tree has bought. The root's completion judgment — the coordinator's owned question — is no longer "do I believe all this work?" It is a ledger: every leaf closed with evidence, every joint tested, the root's own end-to-end evidence green. Belief has been replaced by an audit trail. And the deeper reason this matters is one we set out with: for most real tasks there is no ground truth to check against — there is only whether the human accepts the result as correct. Evidence is how a decomposed system earns that acceptance: not "trust us," but "here is the tree, here is each piece's proof, here is the proof they fit."

Reading the tree
  • In Example 2, suppose there had been no per-subtree evidence — only the failed end-to-end check. What is the recovery procedure, and what does it cost compared to what happened?
  • Soft evidence: the documentation critic scored 5,4,5. What keeps this from being the actor grading its own homework? List the specific design choices that make a soft check trustworthy.
Your turn

Take a real multi-part goal from your research. (1) Draw the tree to leaves one conversation deep. (2) For every edge: brief, deliverable, declared interface. (3) For every leaf AND every joint: the evidence — write the hard checks as actual commands or conditions, the soft checks as verbatim critic prompts with their bars. (4) Sabotage it: pick the leaf whose quiet failure would hurt most, and check — does its evidence actually catch your sabotage? If not, the evidence, not the leaf, is the bug.