[pr-review-doc-context-enrichment] Work item Doc Context enrichment

[orioltf]

Parent

docs/issues/pr-review-doc-context-enrichment/PRD.md

What to build

Add a new step 4a to commands/review-pr.md that runs after the changed files list (step 4) and in parallel with the local diff and file reading steps (5–7). Step 8 waits for step 4a to complete before launching review agents.

Step 4a fetches the ADO work items linked to the PR via the pullRequestWorkItems API endpoint. If the list is empty, it exits silently with no change to behaviour. For each linked work item, it fetches the work item details (az boards work-item show) and spawns one Doc Context Sub-agent per work item in parallel (single message).

Each Doc Context Sub-agent receives the work item ID, title, and description (HTML), plus the changed files list and the local diff if already available. It produces a diff-aware summary of the work item description — focused only on what is relevant to the changed files — and returns a structured block:

### Work item: [{ID}] {Title}
{diff-aware summary}

Step 4a collects all sub-agent outputs, prepends a ## Business context for this PR header, and stores the result as DOC_CONTEXT. Step 8 injects DOC_CONTEXT as a preamble before the diff content in every review agent prompt. When DOC_CONTEXT is empty (no work items, or all sub-agents returned nothing useful), the preamble is omitted and step 8 behaves exactly as today.

Acceptance criteria

• A PR with one or more linked ADO work items: review agents receive a ## Business context for this PR preamble with a summarised work item section per item
• A PR with no linked work items: step 4a exits silently, review agent prompts are unchanged
• Multiple work items are all included in the Doc Context block
• Step 4a runs in parallel with steps 5–7 (not sequentially before them)
• When the local diff is not yet available at step 4a time, sub-agents work from the changed files list only
• No new comments or threads are posted to the PR

Blocked by

None — can start immediately.

Comments

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Add step 4a to the review command that fetches linked ADO work items, spawns parallel Doc Context Sub-agents to summarise them, and injects the result as a business context preamble into every review agent's prompt.

Current behavior:
The review command (steps 1–12) passes the PR title, description, diff, and changed file contents to review agents. No work item data is fetched. Review agents have no visibility into the business intent of the PR.

Desired behavior:
A new step 4a runs after the changed files list (step 4) and in parallel with steps 5–7. It calls the ADO pullRequestWorkItems API to get the IDs of all work items linked to the PR. If none are linked, step 4a exits silently and behaviour is unchanged. For each linked work item it fetches the full work item record (az boards work-item show) and spawns one Doc Context Sub-agent per work item in a single parallel message. Each sub-agent receives the work item ID, title, and HTML description, plus the changed files list and local diff (if already available). It returns a diff-aware summary as:

### Work item: [{ID}] {Title}
{diff-aware summary focused on what is relevant to the changed files}

Step 4a collects all sub-agent outputs, prepends a ## Business context for this PR header, and stores the assembled block as DOC_CONTEXT. Step 8 injects DOC_CONTEXT as a preamble before the diff content in every review agent prompt. If DOC_CONTEXT is empty, step 8 behaves exactly as before.

Key interfaces:

• ADO pullRequestWorkItems resource — called via az devops invoke with repositoryId, pullRequestId, and org route parameters; returns { value: [{ id }] }
• az boards work-item show --id {id} --org {ORG_URL} — fields needed: System.Title, System.Description
• Doc Context block header: ## Business context for this PR
• Work item section format: ### Work item: [{ID}] {Title} followed by the summary
• Step 8 prompt preamble injection: DOC_CONTEXT precedes the diff section

Acceptance criteria:

• PR with linked work items: review agents receive a ## Business context for this PR preamble with one section per work item
• PR with no linked work items: step 4a exits silently, review agent prompts unchanged
• Multiple linked work items: all appear in the Doc Context block
• Step 4a spawns sub-agents in parallel with steps 5–7, not before them
• Sub-agents function correctly when local diff is not yet available (work from changed files list only)
• No new comments or threads are posted to the PR

Out of scope:

• Fetching Confluence pages (that is issue 03)
• Any credential handling (no Confluence dependency in this issue)
• Changes to the confluence-client script (that is issue 01)

---

PRD: docs/issues/pr-review-doc-context-enrichment/PRD.md
Migrated from: docs/issues/pr-review-doc-context-enrichment/02-work-item-doc-context-enrichment.md (source removed after migration)
Touched by PRs: #19, #21, #25