docs agent failed: changelog entries missing links to the originating PRs

TL;DR

Derive PR numbers from merge commits or the GitHub API when generating entries, and render them as links. Entries without PR links are hard to audit.

Error

(changelog lists "Fix login timeout" with no PR link; the PR exists; no error text)

Steps

1. Check how the writer builds entries: if it reads commit messages only, PR numbers are unavailable unless the message contains them. Expected: the writer's data source identified.
2. Prefer merge commits or the GitHub compare API, both of which carry the PR number, over raw commit messages. Expected: a PR-number source selected.
3. Update the entry template to render the link, e.g. referencing the PR by number with the repo URL pattern your host uses. Expected: entries include clickable PR references.
4. Regenerate the changelog for the range and spot-check entries against actual PRs. Expected: links present and correct.

When to use

• Generated changelogs lack PR links
• A docs agent writes entries from commit messages
• Audit or support needs traceability from entry to PR

When not to use

• The changelog is hand-written (an authoring choice)
• Commits are squash-merged without PR references (fix the merge strategy or message format)
• PR links exist but are wrong (a mapping bug)

Tool compatibility

GitHub, GitLab, and similar hosts; conventional-changelog and release-please both support PR linking.

Variant phrasings

squash merges lose the PR number

Configure the merge to keep the PR reference in the message, or query the API by commit SHA.

links present for some entries only

The writer handles one commit style but not others. Normalize the input or extend the parser.

Why it happens

Commit messages are the lowest-common-denominator input, and plain commits do not carry PR numbers. Writers built on messages alone cannot invent the links, so entries ship without them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_v8erdiLLRTiKtbBNraQIJQ