API package reviewer brief

Owner of what the PM sends a package 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 a package 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, one fresh reviewer per package that has package-unique items (uniqueCount > 0). A package with none gets no package reviewer.

Supply

  • the API reviewer workflow link, and the instruction that this is the package role;
  • the input path, the package’s inputPath from the plan’s packageReviewers (.authoring-kit-cache/agents/authoring-kit-reviewer/api-review/<run-id>/package-inputs/<slug>.json, 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 package slug, apiHash and uniqueCount, and the indexHash, taken from the plan (packageReviewers) and the indexHash the PM built, never from another report;
  • the same timestamp as the estate reviewers (a retry takes its own, captured just before it is dispatched);
  • exactly one report path, the package’s reportPath from the plan’s packageReviewers (.authoring-kit-cache/agents/authoring-kit-reviewer/api-review/<run-id>/package-reports/<slug>.md, in the cache; the merge copies it into the committed run folder).

Every package reviewer gets the same brief apart from its package. Never include clusters, the estate report, another package’s input or report, scores, or ledgers. Never fork the PM conversation or reuse a reviewer context.

What the reviewer is told

  • Review only the package’s unique items, under clarity, completeness and accuracy. Consistency is not assessed: unique descriptions have nothing to be consistent with.
  • clusterIds in the input name the shared items judged elsewhere. Do not review or mention them.
  • A rewrite’s replaces is []. Cite item keys in items.
  • Read the input in full; it has one unique item per line. If a read is truncated, re-read the rest by line range. The input’s itemCount is how many unique items there are: return the number you actually read and assessed as itemsReviewed (the merge compares it with itemCount and marks the package partial, with a warning, when they differ; it never blocks).
  • 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.

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 (#package-report) are literal in the template, and the unique-item wording is the same for one item or many. Fields: {{slug}}, {{item-count}} (the plan’s uniqueCount from check-fresh.mjs; equal to the input’s itemCount), {{api-hash}}, {{input-path}} (the plan’s inputPath for the package), {{report-path}} (the plan’s reportPath for the package), plus the shared {{workflow-path}}, {{rubric-path}}, {{rubric-version}}, {{index-hash}} and {{timestamp}} as in the estate brief.

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 the package’s assigned cache reportPath, checked with the path.resolve command in the mode, step 6; reject any other path. Do not open the report. The merge validates it; an invalid or missing report makes that package incomplete and the PM retries it once (retry).

See also