expert-synthesis

What It Does

Reads everything the experts produced and synthesises it into one readiness call. The experts each looked through their own lens; the chief reads across all of them plus the script's deterministic merge, and does what no single expert can: it accepts or declines each finding with a reason, it recommends a resolution for every conflict two experts raised (a recommendation, never applied — that becomes a decision the human makes), it names the gaps no expert covered, and it gives a verdict of ready, needs-answers, or not-ready.

The chief may accept, decline, or flag a gap. It may not invent a finding of its own — every finding id it accepts or declines must be one the merge already knows. The pipeline script enforces that, and turns each conflict into one spec.expert_conflict decision packet.

Use This When

• The spec pipeline is running with the expert roster on, the experts have written notes, and the script has merged them (expert-merge.json exists). Run this once, after the notes step.

Do not run it when no expert fired — the chief only runs when at least one expert did.

Inputs

• merge_path — required. The merged findings (each with an id) and the conflicts, from the script.
• notes_path — required. The raw expert notes, for the reasons behind each finding.
• request_path — required. The request text.
• grounding_path — required. The grounding, so a finding that contradicts the docs is a gap.

Read references/synthesis-checklist.md for the gap categories to look for.

Procedure

1. Read the request, the grounding, the notes and the merge.
2. For every merged finding id, accept it, or decline it with a one-line reason. Cover each id exactly once — an unaccounted finding is a gap in your own read.
3. For each conflict in the merge, write a recommendation that is one of that conflict's claims, verbatim, plus a rationale. Do not apply it; it becomes a decision the human resolves.
4. List the gaps by the categories in references/synthesis-checklist.md: an uncovered area, a contradiction with the grounding docs, a requirement with no owner answer, a missing non-goal, a missing failure path. Attach a plain-language question to a gap that needs one.
5. Give the verdict — ready, needs-answers, not-ready — and hand over the questions worth asking (business words; the plain-language check applies).
6. Validate with scripts/lint-output.sh, then hand the file to the pipeline: paqad-ai spec pipeline experts synthesis <file>.