Subagent Review Skill

1. Review Workflow

1.1. Pre-flight Check

BRANCH=$(git rev-parse --abbrev-ref HEAD) if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then echo "HALT: On main/master branch." fi

if ! git diff --quiet main...HEAD; then echo "Diff detected: code review." else echo "No diff detected." fi

If code/PR review was requested and no diff exists: halt and report. Do NOT fall back silently to design review.

1.2. Setup (Fully Automatic)

Item Detection

review_type git diff main...HEAD has output -> code, else design

scope Always git diff main...HEAD

context Directory name pattern (see 1.4.1)

1.3. Finding Output Format

Every finding from every subagent MUST use this format. Define once here; all task prompts and summaries reference this section.

[{SEVERITY}] {concise title}

What: {specific description — what is wrong, not "could be improved"} Why: {concrete impact — what breaks, what degrades, what risk arises} Where: path/to/file.ext:line — relevant code snippet Confidence: High / Medium / Low Fix: {exact code change as before/after, or concrete action step} {NOT "consider improving X" — show the actual fix}

Severity levels:

Level Meaning

BLOCKING Must fix before merge; correctness or security

IMPORTANT Should fix; maintainability or reliability

MINOR Nice to fix; style or minor improvement

Rules:

• Each finding MUST have all 5 fields (What/Why/Where/Confidence/Fix)

• "What" must be specific enough to locate the problem without reading the file

• "Why" must explain the consequence, not just restate the problem

• "Fix" must be a concrete code diff or exact action, not a suggestion to "consider"

• When no findings exist: state "No findings from {ROLE} perspective."

1.4. Review Execution

1.4.1. Step 1: Auto-detect and Prepare

1. Save diff

DIFF_FILE=$(mkoutput --dir reviews --label review-diff) git diff main...HEAD > "$DIFF_FILE"

2. Detect review_type

if [ -s "$DIFF_FILE" ]; then REVIEW_TYPE="code"; else REVIEW_TYPE="design"; fi

3. Detect context from directory name

DIR_NAME=$(basename "$(git rev-parse --show-toplevel)") PR_NUM=$(echo "$DIR_NAME" | rg -o --pcre2 'pr-\K[0-9]+' || true) ISSUE_NUM=$(echo "$DIR_NAME" | rg -o --pcre2 'issue-\K[0-9]+' || true)

4. Fetch context metadata

CONTEXT_FILE=$(mkoutput --dir reviews --label review-context) echo "# Review Context" > "$CONTEXT_FILE"

if [ -n "$PR_NUM" ]; then echo "## PR #${PR_NUM}" >> "$CONTEXT_FILE" gh pr view "$PR_NUM" --json title,body,comments >> "$CONTEXT_FILE"

Chase references in PR body

gh pr view "$PR_NUM" --json body --jq '.body'
| rg -o --pcre2 '#\K[0-9]+' | sort -u | while read -r REF; do echo "## Referenced #${REF}" >> "$CONTEXT_FILE" gh issue view "$REF" --json title,body,comments >> "$CONTEXT_FILE" 2>/dev/null
|| gh pr view "$REF" --json title,body,comments >> "$CONTEXT_FILE" 2>/dev/null
|| echo "(not found)" >> "$CONTEXT_FILE" done elif [ -n "$ISSUE_NUM" ]; then echo "## Issue #${ISSUE_NUM}" >> "$CONTEXT_FILE" gh issue view "$ISSUE_NUM" --json title,body,comments >> "$CONTEXT_FILE" fi

1.4.2. Step 2: Launch cc x 5 (Single Message, Parallel)

Launch 5 Task tools in one message:

Priority Role Focus

1 security Vulnerabilities, injection, secrets

2 architecture Patterns, dependencies, structure

3 historian History, context, intent alignment

4 code / data Code review: code. Design review: data

5 qa Acceptance criteria, edge cases, coverage gaps

Task prompt template:

[SUBAGENT capability=READONLY] Review from {ROLE} perspective. Diff: {DIFF_FILE} Context: {CONTEXT_FILE}

Investigation steps:

1. Read the diff file in full
2. Read the actual source files (not just the diff) for surrounding context
3. Read the PR/Issue context for intent and requirements
4. For each concern, verify it against the actual code before reporting

Output each finding using the format in Section 1.3 of subagent-review skill. Use all 5 fields: What, Why, Where, Confidence, Fix. If no findings: state "No findings from {ROLE} perspective."

1.4.3. Step 3: Launch cx x 5 (Background)

for ROLE in security architecture historian data qa; do FILE=$(mkoutput --dir reviews --label "review-${ROLE}-cx") codex exec --sandbox workspace-write -o "$FILE"
"[SUBAGENT capability=READONLY] Review from ${ROLE} perspective. Diff: ${DIFF_FILE} Context: ${CONTEXT_FILE}" & done wait

NEVER use & with codex exec if output interleaving is a problem. Use sequential loop instead (remove & and wait ).

1.5. Reviewer Deliberation (Optional)

Execute only when:

• Running as orchestrator (role name is "orchestrator")

• User explicitly requests deliberation

For standalone execution, Section 1.4 alone is sufficient.

1.5.1. Deliberation Prompt

Share all Phase 1 results with each reviewer and ask for additional findings:

[SUBAGENT capability=READONLY]

Phase 1 Review Results

{All Phase 1 findings sorted by severity}

Questions

From your expert perspective ({ROLE}), based on other reviewers' findings:

1. Additional issues they missed from your perspective?
2. Supplementary concerns triggered by their findings?
3. Contradictions or disagreements with their assessments?

Output each finding using the format in Section 1.3. If no findings: state "No additional findings from {ROLE} perspective."

Launch 10-parallel (cc x 5 + cx x 5) same as Section 1.4.

1.6. Summary Output

SUMMARY_FILE=$(mkoutput --dir reviews --label summary)

IMPORTANT: Generate the complete summary (table + detail) in one pass. Do NOT require a follow-up request for details.

1.6.1. Summary Template

Review Summary

Target

• Type: {review_type}, Directory: {dir_name}

Findings

Phase 1: Initial Review

Phase 2: Deliberation

(Include only when Phase 2 was executed)

Key Findings Detail

(BLOCKING, IMPORTANT, or flagged by 3+ reviewers)

#{N} [{SEVERITY}] {title}

What: {specific problem description}

Why: {concrete consequence — what breaks, what degrades}

Where:

• path/to/file.ext:NN -- problematic code
• path/to/other_file.ext:MM -- same pattern

Reviewers: {role1}-cc, {role2}-cx (list all who flagged this)

Fix:

```lang -- Before {exact current code} -- After {exact corrected code} ```

Coverage

1.6.2. Key Findings Selection

Include in "Key Findings Detail" when ANY condition is met:

• Severity is BLOCKING

• Severity is IMPORTANT

• 3+ reviewers independently flagged the same issue

MINOR findings appear in table only (no detail section).

2. Standalone Usage (Lightweight Mode)

• Execute Section 1.4 only (skip deliberation)

• Create summary per Section 1.6

Skip Section 1.5 to reduce execution time and token usage.