benbrastmckie/nvim/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

# 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 .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:

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).

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:

{
  "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:

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:

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:

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)

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 .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:

# 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:

# 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 .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:

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).