[pr-review-doc-context-spawn-reliability] Wire-up: step 4a rewrite + README + CHANGELOG

[orioltf]

Type: AFK

Parent

docs/issues/pr-review-doc-context-spawn-reliability/PRD.md

What to build

Rewrite step 4a in commands/review-pr.md to fix the three defects that cause the Doc Context phase to be silently skipped:

1. Initialise DOC_CONTEXT='' unconditionally as the first statement in step 4a.
2. Pre-fetch linked work item IDs in bash. If the value array is empty or the command fails, leave DOC_CONTEXT='' and proceed.
3. If work items are found: wait for the diff from step 5, resolve CONFLUENCE_CLIENT_PATH from ${CLAUDE_PLUGIN_ROOT} in bash, then spawn the Doc Context Orchestrator agent via an explicit Agent(subagent_type: "pr-review:doc-context-orchestrator", ...) call with all required context. Store the agent's plain-text output as DOC_CONTEXT.
4. Update the parallelism note: step 4a pre-fetch runs in parallel with steps 5–7; the orchestrator agent spawn waits for the diff from step 5; step 8 waits for the orchestrator to complete.

Also update docs/plans/README.md to add spec 11 to the status table, and add a Fixed entry under [Unreleased] in CHANGELOG.md describing the three defects and the orchestrator extraction.

Acceptance criteria

• DOC_CONTEXT='' is the first statement in step 4a.
• Step 4a contains an explicit Agent(subagent_type: "pr-review:doc-context-orchestrator", ...) call — the intent is not satisfied inline.
• The Agent() call passes ORG_URL, PR_ID, work item ID list, CONFLUENCE_CLIENT_PATH (as an absolute string expanded from ${CLAUDE_PLUGIN_ROOT}), changed files list, and diff.
• No node scripts/confluence-client.mjs relative-path call remains in step 4a.
• The parallelism note correctly reflects that the orchestrator spawn waits for the diff before starting.
• docs/plans/README.md includes spec 11 in the status table.
• CHANGELOG.md has a Fixed entry under [Unreleased] covering the three defects.
• PR with ≥1 linked non-Bug work item and no Confluence links: DOC_CONTEXT is non-empty after a review run; review agents receive the ## Business context preamble.
• PR with no linked work items: step 4a exits silently; DOC_CONTEXT=''; step 8 prompts unchanged.
• No new PR threads or comments produced by the Doc Context phase.

Blocked by

• [pr-review-doc-context-spawn-reliability] ADR-0012 + Doc Context Synthesizer agent #70
• [pr-review-doc-context-spawn-reliability] Doc Context Orchestrator agent #71

---

Agent Brief

This was generated by AI during triage.

Category: bug
Summary: Fix step 4a in review-pr command — initialise DOC_CONTEXT, add explicit Agent() spawn, resolve absolute path

Current behavior:

Step 4a has three defects that cause the Doc Context phase to be silently skipped on every run:

1. No DOC_CONTEXT='' initialisation — the variable is undefined when the phase is skipped
2. No explicit Agent() spawn call — the orchestrator satisfies intent inline and proceeds without spawning anything
3. confluence-client.mjs is referenced with a relative path that fails when the working directory is the reviewed project's root

Desired behavior:

Step 4a in the review-pr command is rewritten so that:

• DOC_CONTEXT='' is the first statement
• If no work items are linked, the step exits silently with DOC_CONTEXT=''
• If work items are found, an explicit Agent(subagent_type: "pr-review:doc-context-orchestrator", ...) call is made — never satisfied inline — with all required context: ORG_URL, PR_ID, work item IDs, CONFLUENCE_CLIENT_PATH (absolute string from ${CLAUDE_PLUGIN_ROOT}), changed files list, and diff
• The agent's plain-text output is stored as DOC_CONTEXT
• The parallelism note reflects the correct sequencing: pre-fetch runs in parallel with steps 5–7; orchestrator spawn waits for the diff; step 8 waits for the orchestrator

docs/plans/README.md includes spec 11 in the status table. CHANGELOG.md has a Fixed entry under [Unreleased] covering the three defects.

Key interfaces:

• review-pr command step 4a — the Agent() call must name subagent_type: "pr-review:doc-context-orchestrator" explicitly
• CONFLUENCE_CLIENT_PATH — resolved as "${CLAUDE_PLUGIN_ROOT}/scripts/confluence-client.mjs" in bash before the spawn
• DOC_CONTEXT — string; empty when no work items are found, plain markdown block otherwise

Acceptance criteria:

• DOC_CONTEXT='' is the first statement in step 4a
• Explicit Agent(subagent_type: "pr-review:doc-context-orchestrator", ...) call present — intent not satisfied inline
• Agent() call passes all required context variables
• No node scripts/confluence-client.mjs relative-path call remains in step 4a
• Parallelism note correctly reflects orchestrator spawn waiting for the diff
• docs/plans/README.md includes spec 11
• CHANGELOG.md has a Fixed entry under [Unreleased]
• PR with ≥1 linked non-Bug work item: DOC_CONTEXT non-empty after a review run
• PR with no linked work items: step 4a silent; DOC_CONTEXT=''
• No new PR threads or comments from the Doc Context phase

Out of scope:

• The agent file implementations (issues 01 and 02)
• Changes to confluence-client.mjs or its tests
• Thread posting, re-review logic, or Bot Signature
• GitHub PR support, caching, or Jira sources

---

PRD: docs/issues/pr-review-doc-context-spawn-reliability/PRD.md
Migrated from: docs/issues/pr-review-doc-context-spawn-reliability/03-wire-up-and-housekeeping.md (source removed after migration)
Touched by PRs: #23, #25