obsidian-owl/sw-review

Specwright Review

Goal

Surface PR review comments, triage autonomously per Google severity framework (protocols/decision.md), draft replies, and present for approval before posting. When the associated Specwright work can be resolved safely, use review-packet.md, approvals.md, and unit evidence as the primary reply context instead of reasoning from the diff alone. Stateless with respect to Specwright state — never modifies workflow.json.

Fetch all comment types, group by status, apply autonomous triage:

• Functional issues (API misuse, missing validation): fix code and draft reply
• Nits (style, naming): acknowledge, apply if <2 minutes
• Suggestions: apply if they improve code health, push back with reasoning if not
• Conflicting comments: follow the one most aligned with constitution/spec

The PR itself is the review surface — reviewers see replies directly. When no associated work can be matched, say so explicitly and use a diff-only fallback.

Inputs

• {projectArtifactsRoot}/config.json — git.prTool and git.baseBranch settings
• Current branch: detected via git branch --show-current
• GitHub PR: discovered via gh pr list --head {branch}
• PR comments fetched via gh api REST and GraphQL endpoints
• Associated Specwright work when it can be matched safely from PR number or branch:
  • {repoStateRoot}/work/*/workflow.json
  • {workDir}/review-packet.md
  • {workArtifactsRoot}/{workId}/approvals.md
  • {workDir}/evidence/*.md

Outputs

• Grouped display of all PR comments by status and type:
  • Unresolved threads (highest priority, shown first)
  • Open issue comments (general PR conversation)
  • Resolved or addressed threads (shown last)
• Each comment shows: author, timestamp, file path, line number (where applicable), and body
• When associated work is available, replies and findings use the review packet, approval lineage, and evidence as first-class context
• User responses posted via gh api POST to the appropriate endpoint
• Resolved threads marked via resolveReviewThread GraphQL mutation

Constraints

PR detection (MEDIUM freedom):

• Detect the current branch with git branch --show-current. If the result is empty or HEAD is detached, report the detached HEAD condition and stop.
• Discover the associated PR using gh pr list --head {branch} --json number,title,url. If no open PR is found, retry with --state merged as a fallback for merged PRs.
• If multiple PRs are returned and interactive questioning is available, use AskUserQuestion to disambiguate. In headless mode, use the most recent and record the fallback choice in output.
• If a PR number is passed as an argument, use it directly instead of detecting from the current branch.
• Read config.git.prTool before invoking gh; if the value is not gh or is unset, degrade to URL display. sw-review only supports the gh CLI.

Comment fetching (MEDIUM freedom):

• Fetch all three comment types via gh api:
  • Issue comments (general PR conversation): GET /repos/{owner}/{repo}/issues/{n}/comments
  • Review comments (inline code comments): GET /repos/{owner}/{repo}/pulls/{n}/comments
  • Thread resolution state: GraphQL query on reviewThreads with isResolved field. To correlate: match REST review comment id against GraphQL reviewThreads.comments.nodes[].databaseId. If correlation fails, treat as unresolved.
• Cap fetched comments at 50 per type using --per-page 50. If exactly 50 results are returned, assume more may exist and display: "Showing first 50 — view full thread at {url}." Pagination state is in Link response headers, not in the JSON body.
• Display each comment with: author (user.login), timestamp (created_at), file path and line number (path, line) for review comments, and body text.

Comment grouping and prioritization (MEDIUM freedom):

• Present unresolved review threads as the highest priority group at the top.
• Group comments into categories: unresolved threads, general issue comments, resolved threads. Do not interleave types.
• Within each group, order by timestamp (newest first for unresolved, oldest first for general comments).

Associated work context (MEDIUM freedom):

• Resolve the associated work from PR context by matching the explicit PR number when provided, then workUnits[].prNumber, then the PR head branch against workflow.json.branch. If more than one work matches, report the ambiguity and fall back instead of picking one silently.
• When a unique associated work is found, load review-packet.md, approvals.md, and unit evidence before drafting replies or validating bot comments.
• Use review-packet.md as the primary reviewer-response context. Use approvals.md to verify approval lineage claims and evidence files to verify gate-status claims. Do not default to diff-only reasoning when these audit artifacts are available.
• If no work match is available, say so explicitly and use diff-only fallback.

Responding and resolving (MEDIUM freedom):

• To post a reply to a review comment, use gh api with an HTTP POST: gh api --method POST /repos/{owner}/{repo}/pulls/{n}/comments/{id}/replies.
• To post a new top-level PR conversation comment, POST to /repos/{owner}/{repo}/issues/{n}/comments with a body field. Issue comments have no threading — there is no in_reply_to_id for this endpoint.
• To resolve a review thread, call the resolveReviewThread GraphQL mutation via gh api graphql. The gh pr edit command is for PR metadata only — it cannot post replies or resolve threads; always use gh api instead.
• In clone-local work-artifact mode, replies must quote or paraphrase the relevant packet/evidence summary instead of depending on local-only file links. In tracked work-artifact mode, replies may reference tracked audit artifact paths or sections when that improves reviewer navigation.
• After the user responds, re-fetch the relevant comment to confirm the reply was posted.

Graceful degradation without gh (LOW freedom):

• If gh is not available or not installed, degrade gracefully: construct the PR URL from the git remote URL (convert SSH or HTTPS remote to a browser URL), display it, and inform the user: "Install gh CLI to fetch and respond to comments from the terminal." Do not abort or STOP — present the URL as a fallback so the user can open the PR in a browser.
• In headless mode, follow protocols/headless.md.

Stateless utility (LOW freedom):

• This skill is stateless with respect to Specwright state. It never writes workflow.json, never claims exclusive workflow ownership, and makes no state changes to the Specwright workflow. GitHub comment replies and resolutions are allowed, but the skill never writes Specwright project or runtime state.
• It is not a core workflow stage and never claims top-level work ownership.
• Reading config.json for prTool is permitted. No writes to {projectArtifactsRoot}, {workArtifactsRoot}, {repoStateRoot}, or {worktreeStateRoot}.

Protocol References

• protocols/decision.md — autonomous decision framework (Google severity triage, external reply gate)
• protocols/git.md — PR operations, remote URL conventions, gh CLI patterns
• protocols/evidence.md — gate evidence as canonical detail
• protocols/approvals.md — approval lineage contract
• protocols/review-packet.md — reviewer packet contract for reply context
• protocols/headless.md — non-interactive execution and result file format
• protocols/context.md — logical-root config loading

Failure Modes

• Detached HEAD — git branch --show-current returns empty. Report "Cannot detect branch: HEAD is detached. Check out a branch and try again." Do not proceed.
• No PR found — gh pr list --head returns no results and the --state merged fallback also returns nothing. Report "No pull request found for branch {branch}" and exit without error.
• No comments — PR exists but all three comment type queries return zero results. Report "No review comments found on this PR." and exit cleanly.
• Rate limit exceeded — gh api returns HTTP 429, or HTTP 403 with X-RateLimit-Remaining: 0. Surface the error message and the X-RateLimit-Reset time. Ask the user to retry after the reset window.
• Authorization failure — gh api returns HTTP 403 without rate-limit headers. Report "Access denied. Run gh auth status to check token scopes and repository access." Do not retry automatically.
• gh CLI not available — Degrade gracefully: construct PR URL from remote URL, display it, and print "Install gh CLI to enable full comment review from the terminal." Do not abort.