What a playbook must promise, and who can author it
Series date follows the editorial schedule. First published ; updated .
Progressive Crystallization · Part 4 of 10
“Check the interface and tell me what is wrong” is a reasonable request to a colleague. It is an incomplete contract for a reusable playbook.
Which interface? Who may read its status? How old can the observation be? Does “down” mean an observed state, a diagnosis, or permission to do something about it? A reviewer cannot answer those questions by inspecting the prompt alone.
A playbook contract makes the promised behavior inspectable. It should be understandable to the operator who knows the scenario and precise enough for the engineer who implements it. Neither person should have to guess where the authority comes from.
A contract for the fictional status check
The following is an original design for the series' invented lab. It authorizes no access to real equipment. It is deliberately narrower than a troubleshooting procedure: collect eligible evidence and report a status interpretation. Nothing here resets, reconfigures, or repairs an interface.
Requested target, approved source, response format, observation time, and evidence identity must agree.
Only eligible evidence reaches interpretation.
Return “appears up”, “appears down”, or “review required”. Attach the evidence reference and the reason for any rejection.
A supported classification permits only the declared report.
Collection and reporting each use an authorized identity and destination. No branch grants change authority. Uncertainty does not expand the allowed tool set.
- Name, version, and purpose
- Lab status report, contract version 1. Describe one approved observation. The operational owner must be recorded before any real deployment.
- Inputs
- A requested target, an approved observation source, a trusted evaluation time, and the scenario's reviewed freshness limit. The fixture demonstration will supply these locally, not retrieve them from a service.
- Preconditions
- The executor has permission to read this target and report to this recipient. The requested operation matches the contract. The source and format are supported. Required approval, if any, is current and covers this run.
- Evidence schema
- A format identifier, target identity, observation timestamp, evidence identifier, and status value. Check types and required fields. A parseable timestamp must also meet the freshness and clock assumptions.
- Outputs and postconditions
- A report contains the interpretation, evidence reference, and contract version. A review outcome contains a reason instead of a status guess. A reported status does not assert a cause, recovery, or successful delivery to a third party.
- Allowed branches
- Supported evidence reaches the selected interpretation method. Unsupported or uncertain evidence stops for review. No path invokes a new tool merely because the expected answer was unavailable.
- Timeouts and retries
- Set a collection deadline appropriate to the approved lab source. Limit retries and retain distinct observations. A retry needs current authority; a previous permission decision is not permanent permission.
- Approval points
- Apply the scenario's access policy before collection and its disclosure policy before reporting. Any later mitigation requires a separate contract and authority. Do not infer approval from the report's status.
- Failure and recovery
- Missing, malformed, stale, contradictory, or denied evidence produces an explicit terminal reason. Preserve only the permitted evidence. A reviewer can revise the contract or authorize a different investigation.
- Ownership and changes
- Record author, reviewer, operational owner, contract version, dependencies, and retirement or review triggers. Recheck tests when the producer's schema or meaning changes.
The author does not have to be the executor
An operator may know exactly which observation distinguishes two conditions while having no reason to write a parser. A network specialist may identify an exception. A datacenter technician may know that a procedure assumes a maintenance state that is absent today. Engineers can turn that knowledge into an implementation, but they should not erase its provenance.
These contributors can author or correct the contract. Publication review and execution authorization remain separate decisions.
Contributes scenario knowledge, assumptions, and candidate behavior.
Checks evidence, applicability, failure paths, and proposed permissions.
Runs only the operations its current policy permits.
Maintains the contract, receives failures, and decides when to withdraw it.
OWASP's Authorization Cheat Sheet distinguishes authentication from authorization and recommends least privilege, deny-by-default behavior, and permission validation on every request. That supports the separation between an identified author and an authorized operation. It does not prescribe the particular role map above or certify our fictional workflow.
Read access deserves the same specificity. “It only reads” is not an access policy. Reading a different target could disclose restricted information; repeatedly polling an expensive source could create load. The permission check should refer to the target and operation, not simply to whether the tool sounds observational.
Promises become useful at failure boundaries
Suppose collection times out. The contract should return “observation unavailable,” not “appears down.” If the producer later supplies a response after the deadline, the owner must decide whether it belongs to the expired run or a new one. Quietly attaching it to whichever run is active makes the evidence misleading.
Suppose reporting is added as an external delivery operation. A timeout then has a different meaning: perhaps nothing was delivered, or perhaps delivery succeeded and its acknowledgement was lost. Retrying without understanding that state can create duplicate reports. The local fixture exercise does not implement a delivery service and should not pretend that it solved this problem.
The Amazon Builders' Library article on idempotent APIs explains why a caller-provided request identifier can make retry intent explicit, and why recording that identifier must be coordinated atomically with the mutation. Copying an identifier into a playbook is not enough. The receiving system must enforce the promised semantics.
These details belong in the contract because they determine what “done” means. A valid model answer is not a delivered report. A delivered report is not a repaired interface.
Keep the template small enough to review, but make its stopping behavior as concrete as its successful output. The point where it refuses to continue is part of what the playbook promises.
Sources and scope
- OWASP, Authorization Cheat Sheet: authorization versus authentication, least privilege, default denial, and per-request validation. General application guidance.
- Amazon Builders' Library, Making retries safe with idempotent APIs: expressing retry intent and coordinating request records with effects. API design guidance, not an implementation supplied by this article.
The contract and responsibility map are design proposals for an invented lab. They do not represent an employer's implementation, approval policy, or security certification.