# API-change review planning worksheet


Companion to [the patterns guide](/blog/ai-agent-orchestration-patterns/). **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.

| 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](https://docs.paperclip.ing/guides/day-to-day/issues/), 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

```text
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:
```