Base directory for this skill: /Users/nodo/.claude/skills/entire-adversarial-review

Entire adversarial review

Deliver an evidence-backed review, a session visible on the intended trail, and a concrete request to publish the findings. Prefer the Entire CLI for trail reads, session attachment, findings, and verification. Use Git and gh for source and PR metadata as needed. The Entire MCP tools (get_entire_trail, trail_findings, trail_gates) are fine for reads; do not use them to post findings or attach sessions.

Scope and authorization

Explicit invocation (/entire-adversarial-review, or the user naming this workflow) authorizes attaching the current review session and, if necessary, pushing one empty checkpoint-link commit to the selected open trail branch. Explain each action as you take it; do not ask again when already authorized.
Automatic skill discovery alone does not authorize transcript uploads or branch pushes. For a plain review request, complete the review first and confirm with the user before those mutations.
Honor narrower instructions such as review-only or no pushes. Do not fix code, merge, approve, deploy, or alter unrelated branches.
Ask before posting findings, unless the user already explicitly authorized posting them. Prepare the exact findings before asking. If there are none, say so without creating an empty review discussion.
Read applicable repository instructions (CLAUDE.md, AGENTS.md). Respect actual validation restrictions; do not generalize one repository's prohibition on cloud or Terraform commands to other repositories.

Review the live change

Resolve the project trail, repository change, branch, base, and current head SHA. Project and repository numbers differ: in /gh/OWNER/-/trails/PROJECT_NUMBER/changes/REPO/CHANGE_NUMBER, CLI project selection uses PROJECT_NUMBER, while repository API routes use CHANGE_NUMBER.
Inspect local status and preserve the user's checkout. When source or line anchoring requires it, use an isolated detached worktree at the reviewed SHA (git worktree add --detach "$scratch/review-$sha" "$review_sha" under the scratchpad). Refresh the remote branch before trusting local refs.
Read the complete diff and the smallest adjacent contracts that could invalidate it. Challenge the intended outcome: missing cases, defaults, inheritance, concurrency, retries, failure recovery, rollout ordering, and rollback behavior as relevant. Treat existing automated findings as leads, not evidence. For large diffs, fan out read-only Explore subagents per area, but verify every candidate finding yourself before keeping it.
Run focused, meaningful validation. Verify external API/provider behavior against current primary documentation. Distinguish reproduced failures from static reasoning and untested deployment behavior. Absence of findings in sampled production data does not prove an exhaustive list of enabled behavior.
Recheck the head before finalizing. If substantive code changed, review the delta before carrying findings forward. Separate code findings from CI, draft/conflicts, approvals, and Entire Gates.
Prepare each actionable finding with priority, confidence, exact file/line, trigger, impact, recommended correction, reviewed SHA, and validation boundaries. Avoid speculative findings and style-only noise.

Attach the review session

Discover the installed CLI flags with entire session attach --help and entire checkpoint explain --help. Read the current session ID from $CLAUDE_CODE_SESSION_ID (it matches the transcript ~/.claude/projects/<project>/<id>.jsonl); never copy a session ID from an example or an earlier session.

From the target repository, preview attachment to the reviewed commit, not the checkout's current HEAD:

Without a TTY, attach prints its plan and exits non-zero without changing anything — that output is the preview. Declare only skills actually used. Inspect it: which checkpoint, which commit, whether history would change, and what would be pushed. Under the authorization above, rerun with --force when it matches the requested operation. A pushed commit should be left unchanged. Stop if the preview would rewrite unrelated history or upload unrelated pending checkpoints; isolate the operation first.

If the sandbox blocks macOS Keychain access, rerun the same authorized command with the sandbox disabled (the user approves the prompt). Do not log in again or extract credentials. If auth errors look wrong, check which -a git-remote-entire entire for a stale binary first.

Verify the uploaded checkpoint by ID through the remote API:

Confirm the exact session ID and kind: agent_review. A successful upload is not proof the trail displays the session. The commit-SHA form of checkpoint explain can fail for a metadata-only link even when the checkpoint-ID form succeeds.

Verify trail visibility; recover only if needed

Use entire api --help and the current API schema/source to confirm routes and field names. Resolve the repository ID for the current region; never reuse one from another session or region. The currently supported trail session query is:

Call through entire api --to cell, URL-encode query values, and paginate when needed. Verify that the exact session ID appears in this base/head-filtered response. A direct session lookup or unfiltered repo listing is insufficient.

If indexing is pending, wait briefly (use Monitor with an until-loop, not sleep) and recheck with progress updates. If the checkpoint/session is retrievable but the trail list remains empty with history_complete: true, inspect the checkpoint's association. A known failure mode is that session attach records linked_commits metadata for an already-pushed commit, while the trail index recognizes only Entire-Checkpoint Git trailers. Treat this as a diagnosis to verify, not a permanent assumption about the product.

For that verified failure, use the authorized empty-commit fallback:

Confirm the trail is still open and the intended branch exists. Refresh its remote tip. If code moved since review, inspect the delta before proceeding.
Create a disposable detached worktree from the fresh tip in the scratchpad. Do not switch or modify the user's active worktree.
Create exactly one empty commit referencing the existing uploaded checkpoint:

Inspect hooks first. Preserve required checks. If an Entire capture hook would replace this deliberate trailer or capture unrelated work, isolate that hook behavior rather than silently changing the intended checkpoint. Verify the final trailer and that parent and child trees are identical (git rev-parse HEAD^{tree} HEAD~1^{tree}).
Push HEAD:refs/heads/TRAIL_BRANCH normally. Never force-push or amend the shared commit. If a concurrent push causes rejection, fetch and reassess; do not override it.
Query the trail's sessions endpoint again and verify the exact session ID appears. A checkpoint can contain multiple sessions, so this may expose all of them.
Refresh the trail head, findings, and gates. State that checks or approvals may restart. Remove the clean temporary worktree (git worktree remove) and confirm the original checkout remains unchanged.

Do not keep appending empty commits if this fails. After one verified fallback push and a bounded indexing check, report the unresolved link with checkpoint/session/head IDs and the API evidence. Do not call it complete until visibility is verified.

Ask to publish, then post precisely

After review and attachment verification, present the concrete findings and ask "Post these findings to the trail?" with AskUserQuestion (options: post all / post a subset / don't post). This is the publication boundary requested by this workflow, not a request to approve the code. If posting was already authorized, proceed directly.

Use entire trail finding add --help and the current CLI. Select the project trail, repo, and branch explicitly. For example:

Run line/range-anchored publication from a checkout of the reviewed source (the review worktree). The CLI hydrates selectedText from the local working tree even when --branch selects another remote branch. Posting from an unrelated checkout can silently produce the right line number with the wrong selected text. Verify returned path, line, selected text, status, and freshness. For an empty-link commit, source should be byte-identical to the reviewed parent.

Use safe argument handling for multiline bodies: write each body to a scratchpad file and pass --body "$(cat "$body_file")"; never interpolate untrusted text into shell code. Reuse an idempotency key only with identical fields. If a wrong-anchor copy was accidentally posted and location editing is unavailable, post a correctly anchored replacement, verify it, and dismiss only the erroneous copy with a reference to its replacement. Do not dismiss other reviewers' findings.

Report the exact reviewed head, review verdict, validation limits, session visibility, and publication status concisely. Link the trail. Never claim a session is visible merely because the push succeeded, or claim findings were posted while awaiting the user's answer.

ARGUMENTS: https://github.com/entireio/git-sync/pull/129