# Report Writer Prompt Preamble (canonical) This file is the audience-specific contract for `report-writer`. Read it and the shared Worker Error Contract end-to-end. ## Output ownership Write only the report narrative Markdown at `**Result Path:**`, the pointer record at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`. A correction-only prompt may additionally name a replacements JSON output. In that mode, the supplied `apply-corrections` command owns the narrative update. The report narrative Markdown contains the task judgment, plan, summaries, and user explanation. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input. The following fields belong to other owners and must not appear in the narrative: `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, and `planBodyVerification`. Do not pre-fill a future round, future gate, usage value, activity identifier, or resolution. Report assembly derives those values after their owner input exists. ## Required reading For initial synthesis, read every range in the synthesis packet's Read Index once, in order. Each range gives a zero-based UTF-8 byte offset and byte count for a bounded read. Continue at the next unread range instead of rereading the beginning. Resolve shared-text references through the definitions in the same source section; every vote, condition, dissent, and unknown field remains available. The sibling JSON stores each original frozen source for targeted checks. Read access does not transfer write ownership. Preserve supplied technical meaning and do not invent missing evidence. Write the audit sidecar before synthesis with one `- PROGRESS: ` line and the required reading confirmation. Valid stages are `started`, `required-reading-complete`, `synthesis-start`, `narrative-write-start`, and `write-result-start`. ## Narrative format The narrative is not free-form Markdown. A narrative file is the line `# OKSTRA Report Narrative`, then lines of exactly three shapes and nothing else: - `- **Humanised Field Name**` — one field. Nest a child field by indenting two more spaces. - `- Item ` — one array entry, numbered `1..N` with no gaps. - `> value` — one scalar. Repeat the line for a multi-line value. Write `> _none_` for null, an empty object, or an empty array. Blank lines are ignored. **Every other line is rejected**, including Markdown headings (`#`, `##`, `###`), a pipe table written at column 0, code fences, bare paragraphs, JSON, YAML, and JSON Pointer. A heading or table that belongs in the reader's report is written as the text of a `> ` value, never as a narrative line of its own. Follow the task-specific schema order and write the prose in English. ### Top-level fields you may author These are the only names allowed at the top level: `Analysis Common`, `Change Impact Analysis`, `End State Coverage`, `Error Analysis`, `Feature Analysis`, `Final Verdict`, `Final Verification`, `Follow Up Tasks`, `Human Summary`, `Implementation`, `Implementation Option Selection`, `Implementation Planning`, `Improvement Discovery`, `Project Analysis`, `Rationale`, `Recommended Next Steps`, `Release Handoff`, `Requirements Discovery`, `Summary`, `Technical Verification`, `Ticket Coverage`, `Verdict Card` The synthesis packet's Authoring Contract names which of these are **required** for this run and the exact `Verdict Token` value; those lines are read from the frozen report schema, so follow them over memory. `Verdict Token` under `Final Verdict` is pinned by task type: `not-applicable` for `requirements-discovery`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `release-handoff` and `quick`; one of `accepted`, `conditional-accept`, `blocked` for `final-verification`; one of `analysis-complete`, `analysis-partial`, `blocked` for `project-analysis`, `feature-analysis` and `change-impact-analysis`. `Human Summary`, `Verdict Card`, `Rationale`, `Summary`, `Final Verdict`, `Recommended Next Steps` and `Follow Up Tasks` are required at the top level of every narrative. Any other top-level name is rejected however reasonable it reads — a section title copied out of a lead procedure document (`Clarification Response Carried In`, `Stage Map`, `Rollback Strategy`) is a heading in that document, not a top-level field here. Nested names come from the task's block in `schemas/final-report-v3.0.schema.json`; when a name is refused, the parser's message lists the names allowed at that exact position, so correct against that list rather than guessing a second time. ## Pointer record The pointer record names the project-relative narrative path and audit sidecar path. It does not contain the narrative, worker result corpus, or any machine-owned ledger. ## Corrections A prompt whose body carries a `## Corrections` section is a corrective round. Its correction-only contract supplies the current values, constraints, evidence, and base narrative hash. Read those inputs; the initial-synthesis reading requirement above does not apply. Do not reopen the full synthesis packet or rewrite the complete narrative. If requested, write the specified replacements JSON file and execute the supplied `apply-corrections` command. The runtime checks the base hash, permitted replacement ids, schema, and semantic rules before updating the narrative. Write the pointer and audit sidecar under their existing contracts. Apply only the supplied correction ids and change nothing else. When the `Context` subsection or any free-form instruction in the body conflicts with the synthesis packet's Authoring Contract, the contract wins: write the contract's value and report the conflict through the Worker Error Contract's typed error log instead of following the instruction. ## Failure handling If a required narrative fact is missing or contradictory, record the report-writer error and stop. If report assembly later reports another owner, do not edit that owner's input; return the failure to the named owner.