From e1af34035dc4052d0e9845828a08382b20f31f74 Mon Sep 17 00:00:00 2001
From: Jason-Vaughan <95194903+Jason-Vaughan@users.noreply.github.com>
Date: Thu, 18 Jun 2026 12:52:07 -0700
Subject: [PATCH] =?UTF-8?q?Document=20the=20synthesis/reduce=20pattern=20(?=
 =?UTF-8?q?#39=20slice=204)=20=E2=80=94=20no=20reducer=20tool?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Slice 4 of the scatter-gather roadmap, resolved as a docs-only decision:
TangleBrain deliberately does NOT own the reduce step. The orchestrator
synthesises delegate_many's results itself (it holds the original task
context that makes for good synthesis); a *mechanical* stitch can be
offloaded with an ordinary delegate(task=...) call. No dedicated reducer
tool ships — existing primitives cover it, and frontier-side synthesis is
the better default until observability data shows a TB-side reducer would
earn its keep.

Documentation of existing behaviour; no code change.
---
 ARCHITECTURE.md |  8 ++++++--
 CHANGELOG.md    |  9 +++++++++
 README.md       | 10 ++++++++++
 3 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index a3addc2..642c36b 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -151,8 +151,12 @@ extra (`pip install -e ".[delegate]"`). Four tools:
 
 These are the first three slices of a [scatter-gather roadmap](https://github.com/Jason-Vaughan/TangleBrain/issues/39):
 the orchestrator routes a sub-task to any configured backend (by id or capability) and fans batches
-out concurrently. Still ahead: an explicit synthesis/reduce step and orchestration-tree observability
-(which also adds the deferred non-local delegate metering).
+out concurrently. The **reduce step is deliberately not TangleBrain's** — the orchestrator synthesises
+the `delegate_many` results itself (it holds the original task context that makes for good synthesis),
+and offloads the stitch with an ordinary `delegate(task=…)` call when the reduction is mechanical and
+large. No dedicated reducer tool: the existing primitives cover it, and frontier-side synthesis is the
+better default until usage proves otherwise. Still ahead: orchestration-tree observability (which also
+adds the deferred non-local delegate metering) — whose data would tell us if a reducer ever earns code.
 
 ### Measurement — per-task records (`measurement.py`)
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3ba440d..ce9a1be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Internal
+
+- **Documented the synthesis/reduce pattern (scatter-gather roadmap #39, slice 4).** README +
+  ARCHITECTURE now spell out that the orchestrator synthesises `delegate_many` results itself (it
+  holds the original task context), and offloads a *mechanical* stitch with an ordinary
+  `delegate(task=…)` call — so no dedicated reducer tool ships. Documentation of existing behaviour;
+  no code change. The reduce step stays the orchestrator's by design until observability data (a later
+  slice) shows a TB-side reducer would earn its keep.
+
 ## [0.13.0] - 2026-06-18
 
 ### Added
diff --git a/README.md b/README.md
index 1576a2f..e3612ab 100644
--- a/README.md
+++ b/README.md
@@ -230,6 +230,16 @@ observability is on the [scatter-gather roadmap](https://github.com/Jason-Vaugha
 Any non-local target is opt-in and your responsibility under that provider's terms — see
 [DISCLAIMER.md](DISCLAIMER.md).
 
+**Synthesising fan-out results.** The full pattern is decompose → fan out (`delegate_many`) →
+**reduce** → answer. TangleBrain ships the dispatch primitives but deliberately does *not* own the
+reduce step: the orchestrator gets the results array back and combines it itself, because it holds
+the original task context that makes for good synthesis — something a fresh reduce backend lacks. If
+the reduction is instead **mechanical and large** (concatenating generated files, merging many
+summaries into one list — where the original intent doesn't matter), offload that stitch too with a
+normal `delegate(prompt="Combine these results: …", task="summarization")` call, keeping the heavy
+formatting off your frontier budget. No separate "reduce" tool is needed — the existing `delegate`
+covers it.
+
 It needs the optional `mcp` dependency:
 
 ```sh