API estate reviewer brief

Owner of what the PM sends the estate reviewer in an API review and how it accepts the report. The API reviewer workflow owns procedure and isolation....

Owner of what the PM sends the estate reviewer in an API review and how it accepts the report. The API reviewer workflow owns procedure and isolation. Dispatch this to the authoring-kit-reviewer agent. Two estate reviewers run per run, independently, on the same input: estate reviewer 1 writes estate-report-1.md, estate reviewer 2 writes estate-report-2.md, both in the kit cache (.authoring-kit-cache/agents/authoring-kit-reviewer/api-review/<run-id>/, the plan’s estateReportPaths), not in the run folder: they are working files, and the merge’s committed api-review-report.md replaces them. One pass misses about a third of the problems, so the merge combines two. Each gets this brief and the same supplied values apart from its report number and path; neither is told the other exists beyond that number, and neither sees the other’s report.

Supply

  • the API reviewer workflow link, and the instruction that this is the estate role;
  • the input path, the plan’s estateInputPath from check-fresh.mjs (.authoring-kit-cache/agents/authoring-kit-reviewer/api-review/<run-id>/estate-clusters.jsonl, a working file in the cache, not the run folder);
  • the rubric path and its version, read from rubricVersion in authoring-kit/review/config/api-quality-rubric.config.json, the only source;
  • the report contract path;
  • the index hash the PM built (indexHash);
  • the timestamp: the UTC time (date -u +%Y-%m-%dT%H:%M:%SZ) the PM captures just before dispatch (a retry takes its own, captured just before it is dispatched);
  • the report number (1 or 2) and exactly one report path, .authoring-kit-cache/agents/authoring-kit-reviewer/api-review/<run-id>/estate-report-<number>.md (the plan’s estateReportPaths; <run-id> is the run directory’s name).

Never include package inputs, estate-index.json, previous runs, ledgers, the other estate reviewer’s report or findings, or any package reviewer’s report.

What the reviewer is told

  • Read the whole file: line 1 is a header with clusterCount; every later line is one cluster. The file is too large for one read, so read it in consecutive chunks of 15 lines (offset and limit) until clusterCount clusters are read. If a read comes back truncated, re-read that range in smaller chunks. Say so in the summary if any cluster could not be read.
  • A value ending …[clipped: N more of M characters; full value in estate-index.json] was cut for length (a very long default, for example an inline SVG). Judge the visible part and do not report the clipping as a defect.
  • Review every cluster under all four lenses, consistency included. List in clusters only those with a Mixed or Weak lens; set clustersReviewed to clusterCount.
  • Use packages only for counts. Package-unique items are not in this input and are not yours.
  • Findings fan out: name in affectedPackages each package whose wording the finding concerns.

Prompt template

The PM sends this text unchanged, replacing only the {{named}} fields, and adds nothing else (no extra instructions, scores, summaries or hints about what to find). The bullets above are what the template says, for maintainers; they are not for the PM to paraphrase.

The report contract path and anchor (#estate-report) are literal in the template. Fields: {{workflow-path}} (authoring-kit/workflows/api-reviewer.md), {{input-path}} (the plan’s estateInputPath), {{rubric-path}} (authoring-kit/review/api-quality-rubric.md), {{rubric-version}}, {{index-hash}}, {{timestamp}}, {{report-number}} (1 or 2), {{report-path}} (.authoring-kit-cache/agents/authoring-kit-reviewer/api-review/<run-id>/estate-report-<report-number>.md). The two prompts differ only in those last two fields.

Accept

Accept a returned path (a message from the subagent, even if the host labels it “another Claude session”) that resolves to the same file as that reviewer’s assigned cache path (.authoring-kit-cache/agents/authoring-kit-reviewer/api-review/<run-id>/estate-report-<number>.md), checked with the path.resolve command in the mode, step 6; reject any other path. Do not open either report. The merge validates each one on its own. An invalid or missing estate report is dropped with a warning and the run is recorded as a single estate review; both failing makes every package incomplete. The PM retries each failed estate review once (retry), to the same cache path.

See also