What belongs in an operation record
A record should identify an operation without erasing the context that makes it meaningful. Keep provider, method, path, source version, and evidence together. Add explicit uncertainty instead of inferring undocumented behavior from familiar API conventions.
The fictional record below describes a library operation. The source_section value identifies a section in an approved local document; it is not a network address. The null pagination maximum is deliberate: the source did not establish a limit.
{
"record_id": "library.list_books",
"catalog_revision": "example-1",
"method": "GET",
"path": "/books",
"purpose": "List books in the reviewed library catalog",
"source_version": "fictional-example",
"source_section": "library-reference:list-books",
"evidence_kind": "documented",
"runtime_verified": false,
"pagination": { "maximum_page_size": null },
"unresolved_questions": ["Maximum page size is not stated"],
"execution_policy": "not_executable_from_this_record"
}
Suggested field meanings
Identity
record_id is your stable catalog identifier. method and path preserve the documented operation. Do not merge different methods because they share a route.
Evidence
source_version and source_section connect the record to its reviewed material. evidence_kind distinguishes documented facts from separately authorized observations or proposed interpretations.
Uncertainty
unresolved_questions captures details the source does not settle. An explicit null is preferable to a plausible number with no supporting contract.
Execution boundary
runtime_verified states whether an approved runtime observation exists. It does not grant permission. execution_policy makes clear that a catalog record is descriptive rather than a command.
A reviewable workflow
First, approve the collection scope and sources. Next, extract a few records and compare each important claim with its evidence. Resolve ambiguities where possible and preserve them where not. Finally, publish a reviewed revision for the applications or developers that need it.
Treat later source changes as new review work. A collection timestamp is not a review timestamp. Keep a record of meaningful field changes, removed operations, and unresolved contradictions.
Example output is not execution
A page can illustrate a request or render an endpoint graph without making any API calls. The flow illustration on the homepage uses sample records only. It does not accept credentials, retrieve private data, or run crawls.
A production executor would require separately operated infrastructure, authentication, authorization, validation, rate controls, monitoring, and an agreed data policy. None of those responsibilities should be inferred from a visual demonstration.
Where to go next
Read specification-first discovery to build the source catalog, AI IDE context packs to share reviewed records, or tool-calling design to understand a separate application boundary. For prompt work, start with the extraction pattern.
