# Socratic Pr Review

> >

- **Type:** Skill
- **Install:** `agentstack add skill-marcoskichel-empire-socratic-pr-review`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [marcoskichel](https://agentstack.voostack.com/s/marcoskichel)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [marcoskichel](https://github.com/marcoskichel)
- **Source:** https://github.com/marcoskichel/empire/tree/main/plugins/empire-dev/skills/socratic-pr-review

## Install

```sh
agentstack add skill-marcoskichel-empire-socratic-pr-review
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Socratic PR review: lead the author to the defect with a question, do not dictate the fix.
Pipeline: resolve PR → team-review → draft question-comments → re-check vs code → validate one by one → propose verdict → post one review atomically.
This is the one empire-dev skill that writes to GitHub. It posts exactly ONE review, only after the user validates every comment and the verdict.

- Resolve the target PR before anything else.
- Signals, in order:
  - Explicit PR number or URL in the invocation
  - Open PR for the current branch: `gh pr view --json number,url,headRefOid`
  - PR referenced earlier in conversation
- No open PR + no explicit target → ASK; do not guess.
- Derive `OWNER`/`REPO` from the PR's OWN base repo, never from `gh repo view` (the cwd repo may differ from the PR's repo or fork):
  - `gh pr view "$PR" --json number,url,baseRefName,headRefOid` (a bare number resolves against cwd; pass a full URL for any other repo or fork)
  - Parse `OWNER`/`REPO` from the returned `.url` (`https://github.com/OWNER/REPO/pull/N`); set `PR` from `.number`
- MUST echo `OWNER/REPO#PR @ ` + url and confirm it is the intended PR before team-review or any post. A wrong target is unrecoverable once posted.
- Treat `SHA` as provisional here; re-fetch it immediately before posting (see [post-review](#post-review)).

- Invoke the `team-review` skill on the resolved PR; pass the PR number.
- Let team-review pick the roster and return its consolidated tiered report.
- Use the report's Recommended actions as the comment seed set.
- team-review never posts; this skill owns all GitHub writes.

- Convert each Recommended action into one draft inline comment.
- Anchor every comment to `path` + `line` from the diff:
  - Added or context line → `side: RIGHT`
  - Deleted line → `side: LEFT`, only when that line sits inside a displayed diff hunk; else fold into the summary body
  - Span → `start_line` + `line` (same side)
- Inline comments MUST land on lines present in the PR diff. Finding outside the diff → fold into the summary body, never invent a line.
- Drop Single-source low-confidence findings unless the lone specialist owns that category (per team-review tiering). Do not auto-include nits.
- Draft only; nothing is posted in this section.

- Phrase each comment as the question a curious teammate would ask reading the diff.
- Lead with genuine curiosity, not a gotcha. Seek to understand the change, not corner the author.
- Sound natural and conversational. Plain words, thinking out loud. Drop stiff phrasing like "Is `X` guaranteed to be non-null".
- When there's a clear set of answers, name them in the question: "Do `permissions` / `harness-support` replace `allowed-tools` / `compatibility`, or coexist?"
- Two shapes, both valid:
  - Understand intent: "What are the `permissions` values?", "Why drop the retry here?"
  - Surface a gap: "What happens when `items` is empty?" not "This crashes on empty input."
- Assume competence; no rhetorical or leading-to-humiliate questions.
- One question per comment. No stacked questions.
- Example transforms:
  - "Missing null check on `user`" → "Is `user` ever null by the time we reach this?"
  - "This N+1 query is slow" → "How many queries does this loop fire per request?"

- Re-verify EVERY draft comment against the current code in one batch pass, BEFORE the one-by-one validation loop.
- Read the actual file and line; confirm the issue still exists in the diff as drafted.
- MAY use WebSearch / WebFetch to confirm API behavior, version semantics, or library contracts the finding depends on.
- Drop the comment if re-check shows it is wrong, already handled, or off-target. State dropped ones briefly.
- Correct the anchor line if the finding is real but the line drifted.

- Length: short and direct, ideally under 150 characters.
- No fix suggestions UNLESS the fix is unambiguous; only then MAY append a GitHub ```suggestion block.
- Comment prose: no dashes, no emojis.
- One issue per comment.
- Use backticks for identifiers, paths, and symbols.

- Present comments ONE AT A TIME. Never dump the full list.
- For each, show:
  - `path:line` and a 1-2 line diff snippet for context
  - The draft question comment
  - One line on why it matters (tier + category from team-review)
- Then discuss: keep as-is, adjust wording, or drop.
- MUST wait for the user's decision on the current comment before showing the next.
- Track the running set of validated comments; reflect edits verbatim.

- After every comment is validated or dropped, propose the review event:
  - `APPROVE` — no unresolved Must-fix; only questions or nits remain
  - `REQUEST_CHANGES` — one or more unresolved Must-fix comments
  - `COMMENT` — questions worth raising, no blocking stance
- Propose a summary body (MAY be empty). Keep it short; same prose rules (no dashes, no emojis).
- Present verdict + summary; MUST get explicit user approval of both before posting.
- `REQUEST_CHANGES` blocks the PR; MUST confirm the blocking event explicitly, separate from summary approval.
- User MAY override the event and edit the summary.

- Post the ENTIRE review in ONE GitHub API call. Never post comments individually; never create a pending review then submit separately.
- Immediately before posting:
  - Re-fetch `SHA=$(gh pr view "$PR" --json headRefOid -q .headRefOid)`. If it changed since [target-detection](#target-detection), warn the user and re-confirm (anchors may have drifted).
  - Re-display the exact destination + action — `OWNER/REPO#PR @ $SHA`, event — and get a final explicit "post" confirmation. The per-comment gate does not cover the destination.
- Build the payload with `jq` into a temp file; pass every comment `body` and the summary as `--arg` values, NEVER via string interpolation (bodies hold quotes, backticks, `$()`). Then a single POST, deleting the temp file after:

  ```bash
  payload=$(mktemp)
  # Append each comment as data, never interpolated into the JSON:
  comments='[]'
  comments=$(jq -c --arg path "$P" --argjson line "$N" --arg side RIGHT --arg body "$Q" \
    '. + [{path: $path, line: $line, side: $side, body: $body}]' "$payload"
  gh api --method POST "repos/$OWNER/$REPO/pulls/$PR/reviews" --input "$payload"
  rm -f "$payload"
  ```

- `payload.json` shape:

  ```json
  {
    "commit_id": "",
    "event": "COMMENT|APPROVE|REQUEST_CHANGES",
    "body": "",
    "comments": [
      { "path": "src/x.ts", "line": 42, "side": "RIGHT", "body": "..." },
      {
        "path": "src/x.ts",
        "start_line": 40,
        "start_side": "RIGHT",
        "line": 44,
        "side": "RIGHT",
        "body": "..."
      }
    ]
  }
  ```

- With `comments` present, any event MAY omit `body`; with no `comments`, `COMMENT` and `REQUEST_CHANGES` require a non-empty `body` (`APPROVE` MAY always be empty).
- After posting, report the review URL from the API response.
- On API error (line not in diff, stale `SHA`): re-resolve the anchor or `SHA` and retry the single call, max 2 retries. If a retry changes an anchor the user validated, re-confirm that comment first. Never split into multiple posts; surface to the user after repeated failure.

- The only GitHub write is the single review POST in [post-review](#post-review), gated by [verdict](#verdict) approval.
- MUST NOT push commits, edit the PR body, change labels, or comment outside the review.
- MUST NOT modify the code under review.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [marcoskichel](https://github.com/marcoskichel)
- **Source:** [marcoskichel/empire](https://github.com/marcoskichel/empire)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-marcoskichel-empire-socratic-pr-review
- Seller: https://agentstack.voostack.com/s/marcoskichel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.