API reviewer workflow
This contract owns the delegated API description review and the reviewer-to-PM handoff, for both the estate reviewer and a package reviewer. The API review mode owns orchestration. Reviewer workflow still owns page reviews; this file replaces it for API reviews only.
Rule ownership
| Source | Owns |
|---|---|
| API quality rubric | Lenses, clusters versus unique descriptions, rewrite standard |
| API review reports | The report contract and its JSON block |
| API estate index | The shape of the reviewer input |
| Content voice and tone | The voice of every suggested rewrite |
| This workflow | Inputs, isolation, procedure and PM acceptance |
Procedure
- Read this workflow and the assigned brief (estate or package).
- Read the rubric and the report contract at the paths the brief supplies, and the voice skill.
- Read the assigned input in full. Do not read anything else about the packages.
- Examine every item or cluster through the lenses that apply to your role, and check each
description against the metadata beside it (
type,typescriptType,defaultValue,options,required,types). - Assess each lens as Strong, Mixed or Weak. Never state a quality rating: the merge derives it.
- Write one finding per supported problem, each with a quote, a consequence and either a suggested rewrite or one author question.
- Write the report to the assigned path and return only that path.
Do not delegate the review, adjust an assessment towards an expected result, or invent behaviour the metadata does not establish.
Inputs
| Input | Reviewer action |
|---|---|
| Assigned input path | Read it in full. Estate (both estate reviewers, the same file): estate-clusters.jsonl. Package: package-inputs/<slug>.json. Both are working files in the cache folder. |
| Rubric version | Return it as rubricVersion in the report block. |
| Index hash | Return the exact sha256: value as indexHash. |
| Timestamp | Echo the PM-supplied timestamp exactly; never estimate the current time. |
| Package identity | Package reviewer only: return the supplied slug and apiHash exactly. |
| Item count | Package reviewer only: the input’s itemCount. Return the number of unique items actually assessed as itemsReviewed. |
| Clipped values | A value ending …[clipped: …] was cut for length. Judge the visible part; the clipping is not a defect. |
| Assigned report path | Write the complete report here, and nowhere else. Return only this path. |
Isolation
Do not read or use: another reviewer’s report or input (the other estate reviewer’s report above all: the two
estate reviews must stay independent), estate-index.json, estate-summary.json (a cache file),
snapshots, the API ledger, earlier runs, component source, demos or page content. The estate reviewer
never reads package-unique items; a package reviewer never reads clusters. Required guidance (the
rubric, report contract and voice skill) is permitted.
The estate reviewers’ assigned paths are cache files, in .authoring-kit-cache/agents/authoring-kit-reviewer/api-review/<run-id>/,
a folder both share: write only your own file there and never list, open or read the other’s. The reviewer writes exactly one file: the report at the path the brief assigns. It never edits
metadata or any other path. Component descriptions are fixed upstream, in the component source, by a
person.
Report
Follow API review reports: Markdown for people, then exactly one
fenced json block of the matching kind. Quote descriptions in evidence; use F1, F2… with no
severity labels; separate substantive findings from optional polish. Every suggested rewrite follows
the rewrite standard and the voice skill.
The reviewer records the model it actually ran with.
PM acceptance
The PM does not read the report. It requires the returned path to equal the assigned path, then lets
merge-api-review.mjs validate it: a report that fails validation makes that package incomplete and
is retried once with a fresh reviewer. The PM never edits, retypes or rates a report, and never gives
one reviewer another’s report or scores.