Base context and truth validation

Review decisions compare the diff under review with the codebase reality it is changing. This page explains how the review skills establish base-branch context, validate truth, and avoid treating PR prose or model output as enough evidence.

Mental model

Layer	What it proves
Base truth	what base branch does today, using SCSI when indexed or git show <base>:<path> plus local search otherwise
Change truth	what the branch/PR actually does, using local diff plus file reads
Assumption tests	the smallest safe experiment that could disprove the review decision
State-machine checks	ordered/stateful behavior matches an independent model or table before final/merge-ready claims
Quality gates	planned lint/type/test commands once on the integrated final candidate

Using it

Base-branch context and semantic search

Review skills require comparing your local diff/PR against how base, usually main, works today.

Use scoped source/history for targeted questions and semantic search for substantial missing context when useful. Before querying an index, resolve it with list_indices and establish its snapshot. Do not repeat preflight when valid evidence already exists. Record the actual base/head scope and evidence source in the compact review receipt; do not invent a completed index check.

Final truth validation

For non-trivial review decisions — accepting a suggestion, pushing back, or proposing an alternative — apply these lenses in the single final Verify stage:

1. Establish base truth: what base branch does today.
2. Establish change truth: what the branch/PR actually does.
3. Test assumptions: reproduce in /tmp when possible; otherwise run the smallest safe experiment in the worktree.
4. Check state machines: for reviewed behavior that is stateful, parser-like, branch-heavy, or ordered-condition dependent, a /tmp/state-machine-verification/<pwd>/<topic>/<slug>/ harness is required before the change is final, merge-ready, or a review concern resolved.
5. Run quality gates: consume the integrated candidate's planned lint/type/test receipts; do not re-run completed checks. Discover the correct commands from the repo; do not guess.

Reference: skill support

Review modes live under ~/.agents/skills/k-review/references/.

File	Owns
judging_core.md	truth validation, refutation ladder, severity, and all conditional gate triggers
judging_state.md	state-machine, async-derived state, context divergence, and scale gates
judging_change.md	deletion safety, replacement parity, historical archaeology, and sibling-consumer gates
judging_product.md	product-flow, signal-quality, and systemic-risk gates
judging_pipeline.md	integrated coverage, hygiene lenses, and consolidated final findings
review_post_stage.md / review_fixes.md	no separate post-review stage / authorized production before final Verify
shared_rules.md	base-context gate, review persistence, universal publication boundaries, and delivery load edges
review_delivery.md	public-ready drafts, pending-review semantics, verdict selection, and posting procedure
pr_common.md	PR resolution, shared k-github intake entry, pending-review reconciliation, anchoring
pr_context_audits.md	conditional ambient topic exploration and PR necessity/correctly-open audit, loaded only when pr_common.md triggers them
local_changes.md	local diff / branch-delta review
pr_review.md	initial or continued PR review
pr_fix.md	address reviewer feedback
plan_review.md	plan/design-doc review against codebase reality before implementation

Internals (for maintainers)

PR and issue intake

k-github owns shared context intake for issue diagnosis, implementation, review, and context-dependent composition. Read the complete primary issue/PR body and discussion, including applicable review threads, replies, and pending drafts. An issue-derived worktree does not need a PR before intake can run.

Follow references only to settle a named material question about intent, behavior, precedent, or acceptance. Read complete selected discussions and inspect selected media when claims depend on it. Reuse artifacts by canonical identity and stop expansion when the question is answered or access is blocked; incidental links do not require a recursive crawl.

PR review retains its shared snapshot, before-diff intake gate, and pending-review reconciliation. Reading context neither establishes the technical truth of each comment nor authorizes a GitHub mutation.

Pending-review awareness

Pending-review awareness is part of the PR-mode gate:

1. list reviews for the PR.
2. select current-account state == PENDING reviews.
3. read draft comments.
4. compare with submitted comments/replies by the same account.
5. include Pending review reconciliation: in output.

That lets a later posting session reuse, append to, merge, replace, or drop previous-session feedback instead of creating a competing review.

Net-new findings are appended to the existing pending review with GraphQL addPullRequestReviewThread. Delete/recreate is reserved for changing or dropping existing draft comments, which are not PATCH-editable.

Ambient topic exploration

For disagreements or missing rationale, the review skill adds bounded Ambient Topic Exploration:

• build a topic map.
• search related GitHub issues/PRs.
• search GitHub Discussions via GraphQL SearchType.DISCUSSION.
• search Slack MCP public/team channels when available.
• read high-signal hits with the same intake rules.

Skip it for routine reviews where direct context and base-branch context are enough.

PR necessity and correctly-open audit

For other-authored or unknown-author PRs, the multi-agent flow runs a blocking PR Necessity + Correctly-Open Audit before implementation review.

It classifies:

• author intent.
• whether the PR is procedurally correctly open.
• whether the work is still needed.
• whether similar cross-cutting work is already open or recently merged.

Slack evidence is used only when Slack tools are available. Private channels/DMs require explicit consent.