[pr-review-doc-context-enrichment] Confluence page Doc Context enrichment

[orioltf]

Parent

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

What to build

Extend the work item Doc Context Sub-agent (from issue 02) to follow Confluence page links found in work item descriptions.

Each work item Doc Context Sub-agent, after summarising the work item description, extracts all Confluence page URLs from the description text. It then checks whether Confluence credentials are available (node scripts/confluence-client.mjs --check-creds).

If credentials are available: spawn one nested Confluence page Doc Context Sub-agent per extracted URL in parallel. Each page sub-agent invokes node scripts/confluence-client.mjs <url> to fetch the storage-format page body, then produces a diff-aware plain-text summary of the page content (reading through Confluence storage-format XML directly, no dedicated parser). It returns a structured block:

### Confluence — {Page Title} ({URL})
{diff-aware summary}

These blocks are appended after the work item summary section in the Doc Context block for that work item.

If credentials are absent and at least one Confluence URL was found: emit a console warning (never post to the PR):

⚠ Confluence pages not fetched — set CONFLUENCE_URL, CONFLUENCE_USER,
  CONFLUENCE_TOKEN (or configure ~/.unic-confluence.json) to enable
  doc-aware review.

If credentials are absent and no Confluence URLs were found: skip silently.

If a page fetch fails (network error, 401, 403, or any non-2xx): skip that page and emit a per-page console warning:

⚠ Could not fetch Confluence page <url> — <reason>

Continue with whatever other context was gathered. A single failing page does not block the review.

Acceptance criteria

• A PR whose work item description links to a Confluence page, with valid credentials: review agents receive the work item summary plus a Confluence page summary with provenance label (title + URL)
• Multiple Confluence links in one work item: all pages are fetched in parallel and included
• Credentials absent + Confluence URLs found: console warning shown, review continues with work item summaries only
• Credentials absent + no Confluence URLs: no warning, no change in output
• Confluence page returns 403: that page skipped with per-page console warning; other pages and work items still included
• Network error on a page fetch: same skip-and-warn behaviour as 403
• Warnings are emitted to the console only — nothing posted to the PR

Blocked by

• [pr-review-doc-context-enrichment] Confluence page client script + tests #66
• [pr-review-doc-context-enrichment] Work item Doc Context enrichment #67

Comments

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Extend each work item Doc Context Sub-agent to extract Confluence URLs from the work item description, fetch those pages using the Confluence client script, and append diff-aware page summaries to the Doc Context block — with graceful degradation when credentials are absent or a fetch fails.

Current behavior:
Work item Doc Context Sub-agents (from issue 02) summarise work item descriptions only. They do not follow any Confluence links found in those descriptions.

Desired behavior:
After summarising the work item description, each work item Doc Context Sub-agent extracts all Confluence page URLs from the description text. It then runs node scripts/confluence-client.mjs --check-creds to determine whether credentials are available.

If credentials are present: spawn one nested Confluence page Doc Context Sub-agent per extracted URL in a single parallel message. Each page sub-agent runs node scripts/confluence-client.mjs <url> to fetch the storage-format page body, reads through the XML directly (no dedicated parser), and returns a diff-aware plain-text summary as:

### Confluence — {Page Title} ({URL})
{diff-aware summary}

These sections are appended after the work item summary in the work item's Doc Context block.

If credentials are absent and at least one Confluence URL was found: emit a console warning (never post to the PR):

⚠ Confluence pages not fetched — set CONFLUENCE_URL, CONFLUENCE_USER,
  CONFLUENCE_TOKEN (or configure ~/.unic-confluence.json) to enable
  doc-aware review.

If credentials are absent and no Confluence URLs were found: skip silently.

If any individual page fetch fails (any error): skip that page, emit a per-page console warning (⚠ Could not fetch Confluence page <url> — <reason>), and continue with whatever other context was gathered.

Key interfaces:

• node scripts/confluence-client.mjs --check-creds — exit 0 = credentials present
• node scripts/confluence-client.mjs <url> — stdout = storage-format XML; non-zero exit = error with message on stderr
• Confluence page section format: ### Confluence — {Page Title} ({URL}) followed by the summary
• Console warning format: ⚠ Confluence pages not fetched — … (credentials absent) and ⚠ Could not fetch Confluence page <url> — <reason> (per-page error)

Acceptance criteria:

• PR with a work item linking to a Confluence page, valid credentials: review agents receive work item summary + Confluence page summary with provenance label
• Multiple Confluence links in one work item: all fetched in parallel and included
• Credentials absent + Confluence URLs found: single console warning; review continues with work item summaries only
• Credentials absent + no Confluence URLs: no warning, no change in output
• Page fetch returns 403: that page skipped with per-page console warning; other pages and work items still included
• Network error on a fetch: same skip-and-warn behaviour
• All warnings go to the console only — nothing posted to the PR

Out of scope:

• Parsing Confluence storage XML with a dedicated parser — the sub-agent reads through it directly
• Caching page content across review runs
• Fetching Confluence pages linked from the PR description (not via a work item)
• Any changes to the confluence-client script itself (that is issue 01)

---

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