# Briefing contract Every dispatch uses an 8-section brief. Section headings are mechanical — copy them verbatim. Full field-by-field rationale in `@stravica-ai/engineering-pa-core/docs/standards/briefing-contract.md`. ## The 8 sections | Section | What it carries | |---|---| | Goal | One sentence, outcome-shaped. What shipping looks like. | | Trace | How we got here. The reasoning that led to this task. Load-bearing. | | Context | Paths, files, prior decisions, operator preferences relevant to this task. Extracted, not full-file. | | Tools and sources | What tools to use. Which files to read. Which to avoid. | | Boundaries | What is in scope, what is out. Where decide-alone becomes escalate. Shared-parent-state hazards. | | Output format | Structured return-report shape. Return on completion or abort ONLY. | | Done when | Boolean-checkable ship gate. | | Escalation rule | When to stop and report partial. | ## Trace is the field most often missed Without it, workers make locally consistent but globally incompatible choices. The trace is prose the worker reads to understand WHY this task exists — the reasoning, the prior decisions, the operator direction if any. Cognition's Flappy Bird failure mode captures why: workers briefed without trace re-derive context locally and produce output the integration step can't reconcile. ## Load-bearing additions per Rev 4 ### 1. Shared-MCP-session hazard in Boundaries Worktree isolation covers git only. `/tmp`, `$HOME`, network, and MCP tool sessions (Playwright browser, OAuth-gated services like Gmail, Google Drive, Atlassian) all leak to workers AND are shared with the parent. Every brief whose worker will use one of these tools must: - Acknowledge the shared session in the Boundaries section. - Instruct the worker to serialise with any other agent using the same tool, OR use a headless-Node isolation approach, OR explicitly accept the collision risk. Full findings: see `dispatch-envelope.md` § MCP Tool Availability. ### 2. Structured-return-schema requirement in Output format The parent only sees the worker's final message — no streaming, no intermediate tool events, no per-child transcript reads. The Output format section MUST specify the exact return shape the parent expects. Common shape: ``` ### — worker return **Status:** success | partial | escalation **Deliverables checklist (mark each ✓ or note gap):** - [ ] ... - [ ] ... **Files landed:** files, <+lines/-lines> **Handoff notes:** ... **Escalations (if any):** ... ``` For task-group orchestrators, the Output format additionally requires per-worker enumeration (name / role / agentId / status / key artefacts) because the root only sees what the orchestrator reports. ### 3. Checkpoint pattern for long-running dispatches For work expected to run more than ~5 minutes, brief the worker to `SendMessage("main", )` at natural checkpoints. Silence-vs-completion is the only default health signal — insufficient for genuinely long jobs. Checkpoint intervals: at natural task boundaries (finished section 1, moving to section 2), not on a fixed clock. A message every 60 seconds spams; a message every 15 minutes with a real state update is useful. The default posture is NO checkpoints — most dispatches run under 5 minutes and silence-vs-completion is fine. Add checkpoints deliberately when the shape of the work warrants. ## Related - `packages/core/docs/standards/briefing-contract.md` — canonical field-by-field standard. - `dispatch-envelope.md` — capability matrix / depth findings / MCP inheritance / brief-writing implications. - `packages/core/roles/dispatch-briefer/definition.md` — the Briefer role that authors briefs.