CONTEXT(CLONE)
Sign in

API documentation checked against the specification

For: Developer relations lead or API product owner responsible for public documentation

Pattern: Map, verify, reduceRuns todayDesigned for 4 to 200 agents
Get early accessSign in to use

The pain today

The reference pages, the interface specification and the changelog drift apart. Customers build against what the page says, support finds out from tickets, and nobody knows which source is wrong.

The ask

“I attached our API reference pages, the interface specification and the changelog. For each endpoint, tell me where the documentation disagrees with the specification or the changelog, quote both sides, and do not decide who is right when you cannot tell.”

Plain words, as you would say it to a colleague. Edit it to fit your case before you send it.

What you attach or connect

  • API reference pages as text
  • Interface specification
  • Changelog or release notes

The unit of work

One worker task per one endpoint across page, specification and changelog.

Why a swarm fits

Each endpoint is a small self-contained comparison. A worker needs that endpoint's page, its specification entry and the matching changelog lines, never the whole documentation set.

Not for

One endpoint you already suspect is wrong: open the page and the specification side by side.

The decision tree

5 typed decisions, each with an action for every answer

At fixed moments in a run, the engine puts one narrow question to a decision model. The decision model never writes text: it answers yes or no with a probability, picks from listed options, or gives a score, about a small slice of the material. The engine then does exactly what this tree says, which is what makes the run auditable. The thresholds are the template's design values, not measured results.

  1. Planner, while planning

    Scope checkA choice among options

    Before work starts on a unit

    Is this endpoint present in the reference pages, in the specification, or in both?

    Sees only: The endpoint's name and method with the index of pages and specification entries

    Why: Orphans on either side are findings in themselves and must not be silently dropped.

    • In boththenAccept
    • Documented but not specifiedthenMark unresolved
    • Specified but not documentedthenMark unresolved

  2. Before workers, before a task runs

    Small worker or strong modelYes or no, with a probability

    Before a task runs

    Are this endpoint's request and response flat enough, without nested or alternative schemas, for a small worker to compare field by field?

    Sees only: The endpoint's specification entry

    Why: Nested schemas are where cheap workers miscompare; everything else stays cheap.

    • Yes: 0.60 or higherthenAccept
    • Unsure: 0.30 up to 0.60thenEscalate to a strong model
    • No: below 0.30thenEscalate to a strong model

  3. After workers, the judge checks

    Evidence checkYes or no, with a probability

    After a worker answers

    Do the two quoted passages describe the same field of the same endpoint and give it a different type, requiredness, default or allowed values?

    Sees only: The quoted page passage and the quoted specification or changelog line

    Why: Stops a mismatch report built on two different fields that happen to share a name.

    • Yes: 0.85 or higherthenAccept
    • Unsure: 0.50 up to 0.85thenEscalate to a strong model
    • No: below 0.50thenReject and retry

  4. Reconciler, while merging

    Conflict checkA choice among options

    While reconciling

    Does a changelog line mention this field's change, and which source does it agree with?

    Sees only: The mismatch and the changelog lines naming the endpoint

    Why: When the page may be right and the specification stale, the conflict stays open for the owner.

    • Agrees with the specificationthenAccept
    • Agrees with the pagethenMark unresolved
    • No changelog line mentions itthenMark unresolved

  5. Accountable person, before anything is settled

    Person decidesYes or no, with a probability

    Before anything is reported as settled

    Does this mismatch concern behaviour customers may already depend on, such as a required field, an error code or an authentication rule?

    Sees only: One verified mismatch with both quotes

    Why: Whether to fix the page or the product is the API owner's decision.

    Accountable: The API owner decides which source is right and whether the fix belongs in the page or in the product.

    • Yes: 0.40 or higherthenAsk a person
    • Unsure: 0.15 up to 0.40thenAsk a person
    • No: below 0.15thenAccept

The fleet: who does what

Model tiers by role, not brands: you choose the models. Strong reasoning models plan and reconcile, small fast models do the wide work, and the judge is a decision model from a different family, so it does not share the workers' blind spots.

  1. Planner

    A strong reasoning model matches pages to specification entries and changelog lines, and lists orphans on either side.

    Decisions here:1. Scope check

  2. Workers

    Small fast workers from an open-weight family each compare one endpoint's sources field by field, with quotes.

    Designed for 4 to 200 agents, one worker task per one endpoint across page, specification and changelog. Each worker receives only its own unit.

    Decisions here:2. Small worker or strong model

  3. Judge, from a different model family

    A decision model from a different family checks each reported mismatch is visible in the two quoted passages.

    Decisions here:3. Evidence check

  4. Reconciler

    A strong reasoning model groups mismatches by kind and keeps unresolved source conflicts open for the owner.

    Decisions here:4. Conflict check

  5. Accountable person

    The API owner decides which source is right and whether the fix belongs in the page or in the product.

    Decisions here:5. Person decides

Checked before anything is accepted

  • Every mismatch quotes the page and the specification or changelog line
  • Endpoints present in one source only are listed, not dropped
  • Where sources conflict and none is authoritative, the conflict stays open

What comes back

  • Mismatches per endpoint with both passages quoted
  • Endpoints documented but not specified, and the reverse
  • Changelog entries never reflected in the pages
  • Conflicts the owner must settle

What to measure

  • Mismatches confirmed by the API owner
  • Documentation tickets after the fix
  • Hours to audit the full reference
  • Cost per endpoint compared

Names of measures only. No result is claimed for this template.

Templates open in the workspace chat with the ask filled in. Nothing runs until you send it.

Get early accessSign in to use

More in Software engineering

Dependency and licence audit across a monorepo

For: Engineering lead or open-source compliance owner preparing a release, a sale or a customer audit

A monorepo pulls in a very long list of direct and transitive packages, each with its own licence text.

Pattern: Map, verify, reduceNeeds scale5 decisionsDesigned for 40 to 600 agents

Migration impact map across services

For: Staff engineer or platform lead planning a framework, database or shared-library migration

A breaking upgrade touches modules owned by many teams.

Pattern: Hierarchical decompositionNeeds a connector6 decisionsDesigned for 30 to 800 agents

Test case tournament for a module that must not break

For: Quality lead or engineer owning a payment, pricing or permissions module with thin tests

The module that must not break has happy-path tests only.

Pattern: TournamentNeeds a connector6 decisionsDesigned for 20 to 300 agents