# Skill Pr Review Research

> Fetch GitHub PR and Zulip thread data for pr-type review tasks. Invoke for pr research tasks.

- Skill: `benbrastmckie/skill-pr-review-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add benbrastmckie/skill-pr-review-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/benbrastmckie/skill-pr-review-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: benbrastmckie (https://skillmd.com/u/benbrastmckie)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/benbrastmckie/skill-pr-review-research

---


# PR Review Research Skill

Thin wrapper that validates inputs, extracts the `sources` array from state.json,
and delegates to `pr-review-research-agent` to fetch GitHub and Zulip data.

## Trigger Conditions

This skill activates when:
- Task type is "pr"
- `/research` command targets a pr-type review task
- The task was created by `/pr --review` and has a `sources` array in state.json

## Execution Flow

### Stage 1: Input Validation

Validate that:
1. `task_number` exists and resolves to an active project in state.json
2. `task_type` is `"pr"`
3. The task has a `sources` array with at least one entry

```bash
# Check task exists and get task_type
task_type=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num) | .task_type' \
  specs/state.json)

if [ "$task_type" != "pr" ]; then
  echo "Error: Task $task_number has type '$task_type', not 'pr'. skill-pr-review-research only handles pr tasks."
  exit 1
fi

# Check sources array is present and non-empty
sources_count=$(jq --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num) | .sources // [] | length' \
  specs/state.json)

if [ "$sources_count" -eq 0 ]; then
  echo "Error: Task $task_number has no sources. Tasks created by /pr --review populate sources in state.json."
  exit 1
fi
```

### Stage 2: Preflight Status Update

Update status to "researching" BEFORE invoking subagent:

```bash
bash .claude/scripts/update-task-status.sh preflight "$task_number" research "$session_id"
```

### Stage 3: Create Postflight Marker

This skill previously wrote a bare, metadata-free marker via `touch`. Source `skill-base.sh` and
derive `padded_num`/`project_name` (not previously derived anywhere in this skill), then follow
`@.claude/context/patterns/skill-preflight-flow.md`'s Stage 3 (marker creation) so this skill's
marker carries the full Shape A payload, matching every other lifecycle skill:

```bash
source .claude/scripts/skill-base.sh
padded_num=$(printf "%03d" "$task_number")
project_name=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num) | .project_name' \
  specs/state.json)
skill_name="skill-pr-review-research"
operation="research"
skill_create_postflight_marker "$padded_num" "$project_name" "$session_id" "$skill_name" "$operation"
```

### Stage 3a: Read Artifact Number

Read `next_artifact_number` from state.json with reconciliation pattern. Use this for
naming the report file (zero-padded to 2 digits, e.g., `01`).

```bash
artifact_number=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num) | .next_artifact_number // 1' \
  specs/state.json)
artifact_number_padded=$(printf "%02d" "$artifact_number")
```

### Stage 4: Prepare Delegation Context

Build the delegation JSON with PR-specific fields:

```json
{
  "session_id": "{session_id}",
  "delegation_depth": 1,
  "delegation_path": ["orchestrator", "research", "skill-pr-review-research"],
  "timeout": 3600,
  "task_context": {
    "task_number": N,
    "task_name": "{project_name}",
    "description": "{description}",
    "task_type": "pr"
  },
  "sources": [
    {
      "type": "github_pr",
      "url": "https://github.com/owner/repo/pull/123",
      "parsed": {
        "owner": "owner",
        "repo": "repo",
        "pr_number": 123
      }
    }
  ],
  "artifact_number": "01",
  "focus_prompt": "{optional focus, or null}",
  "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json"
}
```

Extract `sources` from state.json:

```bash
sources=$(jq -c --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num) | .sources // []' \
  specs/state.json)
```

Note: Use `jq -c` (compact output) for inline JSON in delegation context.
Use the safe `select(.project_number == $num)` pattern (not `!=`) per jq-escaping-workarounds.md.

### Stage 4a: Memory Retrieval (Optional)

If `--clean` flag is NOT set, retrieve relevant memories:

```bash
memory_context=$(bash .claude/scripts/memory-retrieve.sh "pr review github zulip research" 2>/dev/null || echo "")
```

Include `memory_context` in the delegation context if non-empty.

### Stage 5: Invoke Subagent

Use the Agent tool with:
- `subagent_type: "pr-review-research-agent"`
- Prompt: the prepared delegation JSON

The subagent will:
1. Write early metadata to `.return-meta.json`
2. Fetch GitHub PR data (4 endpoints)
3. Optionally fetch Zulip thread data
4. Write research report to `specs/{NNN}_{SLUG}/reports/{NN}_pr-review-research.md`
5. Write final metadata to `.return-meta.json`
6. Return brief text summary

### Stage 5b: Self-Execution Fallback

**CRITICAL**: If you performed the work above WITHOUT using the Agent tool (i.e., you read files,
wrote artifacts, or updated metadata directly instead of spawning a subagent), you MUST write a
`.return-meta.json` file now before proceeding to postflight. Use the schema from
`return-metadata-file.md` with `status: "researched"` and include the report artifact.

If you DID use the Agent tool, skip this stage -- the subagent already wrote the metadata.

## Postflight (ALWAYS EXECUTE)

The following stages MUST execute after work is complete, whether the work was done by a
subagent or inline (Stage 5b). Do NOT skip these stages for any reason.

### Stage 6: Parse Subagent Return

Read the metadata file:

```bash
cat "specs/{NNN}_{SLUG}/.return-meta.json"
```

Check `status` field:
- `"researched"` -> success, proceed normally
- `"partial"` -> partial success, note in status update
- `"failed"` -> failure, update status accordingly

### Stage 6a: Validate Artifact Content (Non-Blocking)

```bash
report_path="specs/{NNN}_{SLUG}/reports/{NN}_pr-review-research.md"
if [ -f "$report_path" ] && [ -s "$report_path" ]; then
  echo "Report artifact validated: $report_path"
else
  echo "Warning: Report artifact missing or empty at $report_path"
fi
```

### Stage 7: Update Task Status (Postflight)

```bash
bash .claude/scripts/update-task-status.sh postflight "$task_number" research "$session_id"
```

### Stage 7a: Propagate Memory Candidates

If `.return-meta.json` contains `memory_candidates` array with entries, pass them to the
memory vault:

```bash
# Extract and process memory candidates from subagent metadata
memory_candidates=$(jq -c '.memory_candidates // []' "specs/{NNN}_{SLUG}/.return-meta.json")
if [ "$memory_candidates" != "[]" ]; then
  # Log candidates for /learn --task N to harvest later
  echo "Memory candidates available: $memory_candidates"
fi
```

### Stage 8: Link Artifacts in state.json

Add the research report artifact to state.json and regenerate TODO.md:

```bash
# Link report artifact
report_path="specs/{NNN}_{SLUG}/reports/{NN}_pr-review-research.md"
report_summary=$(jq -r '.artifacts[0].summary // "PR review research report"' \
  "specs/{NNN}_{SLUG}/.return-meta.json")

# Update state.json with artifact
bash .claude/scripts/state-write.sh \
  '.active_projects |= map(if .project_number == $num then
    . + {"artifacts": ((.artifacts // []) + [{"type": "report", "path": $path, "summary": $summary}]),
         "next_artifact_number": ((.next_artifact_number // 1) + 1)}
    else . end)' \
  --session-id "$session_id" \
  --argjson num "$task_number" \
  --arg path "$report_path" \
  --arg summary "$report_summary" \
  --regen-todo
```

### Stage 8a: TTS Lifecycle Notification

```bash
bash .claude/scripts/lifecycle-notify.sh "research" "$task_number" "researched" 2>/dev/null || true
```

### Stage 9: Cleanup Marker Files

Follow `@.claude/context/patterns/skill-postflight-flow.md`'s Stage 9 (cleanup), reusing the
`padded_num`/`project_name` derived at Stage 3:

```bash
skill_cleanup "$padded_num" "$project_name"
```

### Stage 10: Return Brief Text Summary

Return 3-6 bullet points summarizing:
- Sources fetched (GitHub PR: N reviews, N comments)
- Zulip status (fetched N messages / skipped: unconfigured)
- Report artifact path
- Key findings (open questions count, requested changes count)

Do NOT return JSON.

## MUST NOT (Postflight Boundary)

After the agent returns -- whether with status researched, partial, or failed -- this skill MUST
proceed immediately to postflight (Stage 6). The skill MUST NOT:

1. **Edit source/report files** - All research work is done by agent
2. **Run domain analysis or calculations** - Analysis is agent work
3. **Use MCP or WebSearch tools** - Research tools are for agent use only
4. **Analyze or grep source** - Analysis is agent work
5. **Write reports** - Artifact creation is done by agent

> **PROHIBITION**: If the subagent returned partial or failed status, the lead skill MUST NOT
> attempt to continue, complete, or "fill in" the subagent's work. Report the partial/failed
> status and let the user re-run `/research` to resume.

The postflight phase is LIMITED TO:
- Reading agent metadata file
- Calling `update-task-status.sh` for status updates (state.json + TODO.md)
- Linking artifacts in state.json
- Cleanup of temp/marker files

Reference: @.claude/context/standards/postflight-tool-restrictions.md

---

## Return Format

Brief text summary (NOT JSON).