API-change review planning worksheet
An illustrative filled map and a blank template for planning a review.
Companion to the patterns guide. Illustrative plan, not a completed run. API details, task labels, sample IDs and artifact revisions are invented. No tasks were created. Dependencies specify required inputs; they do not prove installed scheduling, parallel execution, automatic wake or join.
Filled map
Decision: human API owner accepts, requests revision or holds orders-proposal-v1. Packet: api-review-v1 contains current/proposed contracts, approved criteria and samples legacy-01 (no client_reference), new-01 (field supplied), invalid-01 (empty value). Current POST /orders accepts requests without the field; the proposal requires it.
Criteria: preserve existing valid requests unless the owner approves a versioned breaking change; document invalid-input responses; any migration identifies affected callers and changes. Analyze the packet only; do not edit or deploy the service.
Scroll horizontally to see all columns
| Task / output owner | Input revision / dependency task | Expected artifact | Reconciliation requirement | Human decision |
|---|---|---|---|---|
| P: approve packet / analyst prepares; API owner approves | Proposed api-review-v1 and requirements; no prior task within this map | Approved api-review-v1, criteria and sample IDs | Confirm approval covers this exact packet | API owner approves criteria and scope before reviews |
| C: compatibility / compatibility reviewer | Approved api-review-v1; depends on P | compatibility-findings-v1: packet revision, criterion, sample ID, finding, evidence, unresolved question | Memo owner checks output exists and matches packet; possible finding: required field conflicts with legacy compatibility | Reviewer cannot waive compatibility criteria |
| E: error responses / error-response reviewer | Approved api-review-v1; depends on P, not C | error-findings-v1, same six fields; possible finding: missing empty-value response definition | Memo owner checks output and packet match; a document gap is not observed service behavior | Missing evidence can require a hold |
| M: reconcile / named memo owner | Packet plus both findings; depends on C and E | review-memo-v1: accept/revise/hold recommendation for orders-proposal-v1, supported findings, conflicts and gaps | Require both outputs or explicit reasons they cannot finish; absence means incomplete. Resolve against criteria, not vote counts | API owner decides on exact proposal revision |
| Q: conditional clarification / operator or bounded manager | Unresolved finding plus its packet; depends on the review that raised it | One targeted clarification from authorized owner, evidence and packet-change decision; migration note only if needed | M stays incomplete for a material unresolved question. If packet changes, repeat affected reviews against new revision | Return policy changes to API owner; stop after permitted clarification or mandate limit |
Q is a conditional route, not a third standing review. Name M before assigning branches. First check whether one agent can produce the complete, checkable memo; split only for a distinct needed review.
If using Paperclip’s Blocked-by relation, represent P as a task: relations link tasks. Documentation describes how agents treat unresolved blockers; this worksheet has not tested installed behavior. Task status does not replace checking actual findings.
Blank reusable map
Scroll horizontally to see the full example
Decision and human owner:
Exact proposal revision for the human decision:
Final output and acceptance criteria:
Frozen inputs, revisions and sample IDs:
Scope / actions excluded:
Why one agent is sufficient, or a split is needed:
Repeat for each necessary step:
Task label / purpose:
Input revision(s):
Dependency task(s) / required prior artifact:
Output owner:
Expected artifact / required fields:
Reconciliation requirement / checking owner:
Human decision / authority boundary:
Independent branches / why neither needs the other's finding:
Reconciliation owner / outputs that must arrive:
Revision-match check:
Conflict rule / missing-output consequence:
Conditional route / trigger / permitted next owner:
Work limit / stop or escalation condition:
Changed inputs / reviews to repeat:
Human decision / exact artifact revision / approval record: