Detect documentation gaps introduced by merged code

Why use this

1. A maintainer may merge an interface change whose code tests pass while users still see outdated examples or configuration instructions. Missing documentation can be difficult to spot when changes are spread across several recent merges.

2. This job could compare user-visible changes with the relevant documentation and produce a focused gap report. Distinguishing a confirmed mismatch from a likely documentation need lets maintainers prioritize review without generating noisy automatic edits.

Why an agent / simpler alternative

Useful judgment

Interpret whether a code change affects documented behavior and identify the relevant examples or reference pages.

Simpler alternative

Use a pull-request checklist when changes are small and maintainers know all affected documentation.

Unsuitable when

The comparison requires inaccessible repository content or would edit/publish documentation without authorization.

Proposed inputs

1. Name

   Merged-change set

   Owner

   Repository maintainer

   Minimum scope

   Approved diffs and merge identifiers for a bounded period

   Quality check

   Exclude unmerged work and identify generated files

2. Name

   Documentation snapshot

   Owner

   Documentation owner

   Minimum scope

   Relevant API, CLI and configuration pages

   Quality check

   Match version, branch and product scope

Access and setup — proposed or unknown

Proposed minimum

1. Read supplied diff/documentation copies and create a private report; no repository writes or scheduled jobs.

Compatibility unknowns

1. Current repository permissions, documentation mapping, CLI access and runtime compatibility are unknown.

External actions requiring approval

1. Repository changes, issue creation, scheduled access and posting findings require appropriate approval.

Expected deliverable and review checks

Proposed artifact

Gap report with changed behavior, affected documentation, evidence pointers and proposed clarification.

Critical checks

1. Tie each finding to a merged change; check versioned docs; distinguish absent documentation from unchanged behavior.

Missing output evidence

This overlay adds no new output inspection, execution or validation; consult the referenced canonical source outcome limits.

Failure signals and proposed responses

1. Signal

   A refactor is mistaken for a public behavior change

   Why it matters

   The report creates unnecessary work

   Proposed response

   Compare the external contract and suppress unsupported gaps.

2. Signal

   Current code is compared with an older release's docs

   Why it matters

   A legitimate version difference becomes a false defect

   Proposed response

   Align versions or clearly label the mismatch.

Effort and cost — unknown

Setup work

1. Define change window and documentation ownership.

Ongoing review

1. Review findings and update mappings as interfaces evolve.

Unknowns

1. Repository coverage, generated-doc behavior, review effort and service costs are unknown.

First check — proposed, unexecuted

Status

proposed_unexecuted

Synthetic fixture

Invent three diffs: a renamed CLI flag, internal refactor and new configuration default; supply one outdated and one versioned documentation excerpt.

Acceptance checks

1. Report evidence-backed gaps; exclude the refactor; preserve version distinctions; make no edits.

Stop conditions

1. Stop if merge status or applicable documentation version cannot be determined.

Limits

1. A gap report cannot establish documentation completeness or correctness across uninspected interfaces and versions.