open-horizon-labs /review-readiness
Decide whether RNA context makes a PR or working-tree diff easier to review, then produce the smallest useful review map.
This is a skill, not a fixed report generator. The agent chooses the probes that fit the change. The point is not to prettify git diff; it is to answer review questions that raw diff cannot answer cheaply:
- Which changed symbols are structurally important?
- Which callers, outcomes, guardrails, or docs should a reviewer inspect?
- Which missing metadata actually blocks review, and which does not matter?
- Where is RNA adding value, and where is plain diff already the right artifact?
If RNA adds no value for the current diff, say that directly and review from the diff.
Arguments
$ARGUMENTS may identify the change to inspect:
- empty: current working tree diff
--base main: the two-ref rangemain..HEAD(two dots;search(mode="change")rejects three-dot ranges)--base <sha1> --head <sha2>: explicit range--pr 660: GitHub PR diff
Procedure
Step 0: Try the change bundle first
Before manually assembling diff shape and graph context, call
search(mode="change", query=<scope>) (#899): <scope> is "working_tree"
(default), "staged", or "<base>..<head>" (map --base X to X..HEAD,
--base X --head Y to X..Y, and --pr N to <pr-base-sha>..<pr-head-sha>; always the two-dot form -- three-dot ranges are rejected). This
one call already composes hunk-intersected changed files/symbols, blast
radius (labelled graph-evidenced vs. name-based by Calls-coverage readiness),
tests to run with a no-test gap count, co-change misses, and risk
(churn/complexity/notes/doc-drift) -- most of Steps 1-3 below in one bounded
report. Use it as the primary source and fall back to the manual steps only
for probes it doesn't cover (e.g. reading the actual diff text, outcome_progress,
or drilling into a specific symbol with mode="neighbors"/"impact"
directly).
Step 1: Get the diff shape
Use the cheapest source that matches the argument:
- working tree:
git diff --statand targetedgit diff -- <path>as needed - branch vs base:
git diff --stat <base>...HEADand targeted hunks - PR:
gh pr viewfor title/body/base/head, thengh pr diffor local diff by resolved refs
Do not paste the whole diff unless the user asks. Summarize:
- changed files by kind: code, tests, docs,
.oh/artifacts, config - added/modified/deleted/renamed shape
- whether the diff is mostly behavioral code, review process, docs, tests, or generated/artifact content
- changed hunks with current-side line ranges when available (
+start,count) and deleted-only hunks called out explicitly - for code hunks, whether each hunk is mapped to current extracted symbols, unmapped, deleted-only, docs/config-only, or not covered by the indexed graph
Step 2: Decide whether graph context is worth using
Ask this before querying RNA: what review decision would graph context improve?
Use RNA when at least one is true:
- a changed function/type/module has non-obvious callers or dependents
- a public/exported surface changed
- the diff touches extractor, graph, scanner, service, server, or query boundaries
- the diff appears related to an outcome, guardrail, ADR, or previous metis
- the reviewer needs impact/risk more than line-by-line commentary
Skip RNA and say so when:
- the diff is only docs, session notes, or skill prose
- the only executable change is self-contained and obvious from the diff
- the graph has no indexed symbols for the changed language/file and that absence would not affect the review decision
Step 3: Probe selectively
Use repo-native tools before generic grep/read for code understanding.
Useful probes include:
repo_mapfor unfamiliar subsystem orientationsearch(query=<symbol/file/outcome>, compact=true)to find changed symbols or related artifactssearch(node=<id>, mode="neighbors", direction="both")for local graph contextsearch(node=<id>, mode="impact")when exact downstream impact changes review riskoutcome_progress(outcome_id=<id>)when the diff claims outcome progress- For code files, map current-side hunk ranges to current extracted graph symbols where the index has line ranges. Record the stable node ID for each mapped symbol. If a hunk is deleted-only, top-of-file/import-only, docs/config-only, or outside indexed coverage, keep it at file/hunk level with an explicit reason instead of forcing a symbol mapping.
For a small diff, two or three targeted probes are usually enough. Do not run full-repo LSP, embeddings, or broad enrichment as part of this skill.
Step 4: Classify review readiness
Classify what the reviewer can trust:
- Ready — diff and context are enough to review now
- Partial — review can proceed, but named follow-up probes would reduce risk
- Blocked — a specific missing fact prevents an honest review
Be precise about missing metadata. Avoid generic complaints like “LSP not ready.” Instead say what is missing: exact callers for X, base-side identity for a deleted symbol, graph coverage for Python skill files, stale scan for src/extract, etc.
When RNA verbose output includes review-readiness scoped context, use that workflow-specific line instead of treating global dead-code prerequisites as the review gate. Scoped/root/changed-file LSP coverage is partial for global analysis but can still be enough for review when the missing facts are named.
Step 5: Produce a review map
Output this shape:
## Review Readiness
### Diff Shape
- [files/change categories]
### Hunk Map
| File | Hunk range | Classification | Symbol/node ID or reason |
|------|------------|----------------|--------------------------|
| [path] | [+start,count / deleted-only / n/a] | [mapped / unmapped / deleted-only / docs / config] | [stable node ID or explicit gap] |
### RNA Added Value
- [specific graph/business context that changes review decisions]
- or: RNA adds no material value for this diff; raw diff review is sufficient because [reason].
### Review Anchors
- [symbol/file/outcome/guardrail]: [why reviewer should inspect it]
- [hunk range → stable node ID or explicit unmapped reason]: [why reviewer should inspect it]
### Readiness
- Ready: [what can be reviewed now]
- Partial/Missing: [specific missing facts, if any]
- Not needed: [metadata intentionally skipped]
### Recommended Next Step
- [continue review / run targeted probe / ask for scan refresh / treat as docs-only]
How this ties to #659
#659 says enrichment readiness cannot be one global state. This skill makes readiness job-specific for PR review: start from the user's review task, pull only metadata that helps that task, and keep expensive providers such as LSP scoped to questions they uniquely answer.
The walking skeleton is the agent process. If repeated use exposes a hard mechanical step that agents cannot perform reliably, productize that one primitive in core RNA later.
Guardrails
- Do not claim semantic completeness from line overlap or a clean diff.
- Do not run global dead-code analysis from this skill.
- Do not require full-repo LSP before first-pass review.
- Do not hide when RNA adds no value; that is a valid readiness result.
- Do not replace tests, compiler checks, or the mandatory independent final-diff
/reviewapproval.