fix: describe both related-doc reasons and stop sending a full conventions file twice

[aliasunder]

Summary

The user prompt introduced every related doc with "Documentation that may describe changed code". Priority docs are included whether or not the diff touches them, so that header misdescribed them. The header now names both inclusion reasons and points at each block's reason attribute:

Documentation provided as context — flag any claims that have become stale. A block whose reason is "priority documentation" is included whether or not the diff touches it; every other block's reason names changed files it mentions:

The section stays one section. Each doc block already carries reason="priority documentation" or reason="mentions …", so the header only needed to stop claiming a single reason for both.

A second fix rides along. When the conventions section carries the whole conventions file, the orchestrator is meant to send no other full copy. The related-file scan was not told to skip it, so a JavaScript/TypeScript conventions file that imports a changed file was sent twice: in the conventions section and again as a related-file block. The scan now gets the conventions path as an exclusion in that case.

Changes

• src/orchestrate.ts: findRelatedFiles excludes the conventions file when the conventions section already carries it in full.
• src/__tests__/orchestrate.test.ts: two exact excludePaths expectations now include the conventions path. Two new tests cover the full-section case (the file is excluded and no related-file block carries it) and the truncated case (nothing is excluded, so a related-file block can still carry the full text).
• src/review/prompt.ts:
  • The related-docs header wording.
  • Doc comments name the functions and modules that prompt strings must stay in step with: filterNonFindings, annotateDiff, renderExcludedFilesNote, mergePhaseFindings, and the reason strings readPriorityDocs and findRelatedDocs set. A comment on buildSystemPrompt's section array says the order matters, because sections cite each other as "above" and "below".
  • conventionsRenderInFull's doc lists every case where the conventions section defers to another copy of the file.
  • truncateConventions calls conventionsRenderInFull instead of repeating its length check.
  • renderFileBlock keeps a file's reason on diff-only blocks too. No caller sets a reason on a diff-only file today, so output doesn't change.
  • The conventions, diff, and prior-findings/prior-comments sections are built as open tag, body, and close tag, like the metadata section. The rendered text is unchanged.
• src/review/__tests__/prompt.test.ts:
  • The header test now renders one priority doc and one mention-matched doc and asserts the header plus both blocks as one section.
  • The section-order and omission tests use the new header text.
  • The omission tests for related docs and prior bot comments gain a positive anchor, so an empty prompt can't pass them.
  • New tests cover a diff-only block that keeps its reason, the whole diff section, and conventions rendered in full at exactly the cap.
  • Prompt-section tests that checked fragments now assert the whole section: prior findings, metadata with no description, a related-file block, and the truncated conventions cases.
• src/context/__tests__/workspace.test.ts: a new test feeds the real readPriorityDocs output into buildUserPrompt and asserts the header and the README block together, so renaming the priority-doc reason string on either side fails.

Testing

• 816 tests pass; lint and tsc are clean.
• Mutation checks:
  • Restoring the old header fails the section-order test and the header test.
  • Removing the conventions path from the related-file scan's exclusions fails the full-section test.
• Live check: a temporary commit changed the max_related_docs default in src/config.ts from 10 to 12 without updating README, and a later commit reverts it. On that run README was a priority doc and no doc was mention-matched (priorityDocPaths: README.md, mentionMatchedDocsCount: 0). The review flagged src/config.ts:156 with "Reconcile the max_related_docs default with README's documented value", citing README's input table, so the model read the priority doc under the new header. That run used an earlier draft of the header. It had the same opening line and the same section and block layout, and differed only in how it described the two reasons.

🤖 Generated with Claude Code

[umm-actually]

umm-actually re-reviewed at 2ff5b6a

No new findings (3 tracked finding(s) across all runs).

---

umm-actually · deepseek/deepseek-v4.1-flash