Audit Pr

Audit PR

The manager's "can this ship?" gate. A read-first audit over the entire PR — its SPEC, all phases, docs, tests, CI, and review axes — that returns a single verdict: merge-ready or a ranked list of blockers. Never edits, never refactors. By default it never merges either — the human decides and merges. The one exception is the opt-in auto-merge below: a documented policy (or an explicit user instruction) plus a fail-closed pre-merge checklist.

Turn contract — verify before ending the turn

✓ The verdict block was printed in the fixed format: `VERDICT: MERGE-READY | BLOCKED` with ranked, evidenced blockers
✓ The PR's FULL URL is printed in the verdict header (the user may be juggling
  several projects and agents without a CI monitor — the link in the chat is
  the contract, never "PR #N" alone)
✓ MERGE-READY verdict? Then the MERGE-READY comment was POSTED on the PR
  (`gh pr comment --body-file` RUN, idempotent by SHA marker) — a comment,
  never a commit-message tag. BLOCKED → no comment posted
✓ Nothing was edited or refactored; nothing was merged UNLESS the auto-merge
  policy applied AND the pre-merge checklist was RUN with its output pasted
✓ The closing `→ Next:` block is printed, then the machine envelope (fenced ```json — see ## Machine envelope) as the ABSOLUTE last output

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

When to use

• After the work is "done" and before merging — the final gate once review-change

is clean and all phases are committed.

• When you want one defensible answer to "is this PR actually ready?" rather than

trusting that every loose end was tied off.

review-change reviews the diff for quality; audit-pr audits the PR as a unit of delivery — that everything the SPEC promised is present, traceable, and green.

Scope

The whole pull request: the branch vs. the default base, plus its SPEC and planning artifacts, the roadmap entry, the doc map, the PR body, issue links, and CI. Default target is the current branch's PR; accept a PR number to target another.

Step 0 — Discover the project & the PR (always first)

1. Project contract. Per the agent guide's Workflow conventions +

documentation map, then read what THIS skill needs: the roadmap, the feature/fix templates, and the project's verification gate (type-check / tests / build / CI).

1. The PR. Identify it and read it in full (forge CLI per the project's

Workflow conventions — examples use gh): ``sh gh pr view --json number,title,body,baseRefName,headRefName,isDraft,mergeable,mergeStateStatus,files,commits,statusCheckRollup,closingIssuesReferences ` If no PR number is given, resolve the current branch's PR (gh pr view --json ...`). If none exists yet, audit the branch vs. the default base and say "no PR open yet" — the contract still applies.

1. The SPEC. Locate the governing SPEC — docs/features/-/ (feature)

or docs/fix/-/ (fix) — and its planning artifacts (PLAN.md, TASKS.md, progress.md, testing.md, known-issues.md, decisions.md) when present. The SPEC is the source of truth for what "done" means.

Merge-readiness contract

Check each gate; cite evidence (file:line, criterion, check name, issue number). A gate that can't be confirmed is a blocker, not a pass — never assume green.

| Gate | What it means | Blocker when | |---|---|---| | Acceptance criteria | Every SPEC acceptance criterion is satisfied, each mapped to concrete evidence (code, test, or doc). | Any criterion unmet, unverifiable, or silently dropped. | | All phases complete | Feature: every phase in PLAN.md/TASKS.md is done and logged in progress.md. Fix: the SPEC is fully implemented. | Any unchecked task or unimplemented phase without an explicit, tracked deferral. | | Scope integrity | The PR implements the SPEC and no more; out-of-scope work was split out. | Undocumented scope creep, or in-scope work missing. | | Docs updated | Every "Affected docs" criterion is satisfied; per-phase docs (progress/testing/known-issues/decisions) reflect reality; the doc map still resolves. Never merge with documentation still pending. | A doc the map or SPEC requires is stale, missing, pending, or contradicts the code. | | Traceability | Closes #N is in the PR body when the work is issue-born (from plan-feature-from-issue or plan-fix); the roadmap/fix-index entry matches, is still present (removed only after merge, never before), and carries the linked PR reference (done · [#]()). | Issue-born work without Closes #N; a roadmap/index entry out of sync; the entry dropped before merge; or a done row without its PR link. | | Tests | New behavior is covered at the right layer (prefer integration); acceptance criteria map to tests; no regression-risk tests left red. | New behavior untested, or tests assert nothing meaningful. | | Verification gate / CI | The project's gate passes — type-check, tests, build — and statusCheckRollup is green. | Any required check failing, pending, or absent where the project requires one. | | Mergeability | Branch is off the default base, independently mergeable (no conflicts), not stacked on another PR, not draft. | Wrong base, conflicts, stacked dependency, or still draft. | | Review axes clean | The applicable review-change axes are clean or every remaining finding is consciously deferred to a tracked issue with a trigger. | A fix-now finding still open, or a deferral with no issue/trigger behind it. |

> Run review-change for the axis check if it hasn't been run on the final state, > or read its latest report. Don't re-litigate findings already classified — verify > each open one is either resolved or has a real, tracked home.

> done ≠ merge-ready. A unit flips to done when its PR opens (built, not > merged — merge state lives in the forge). So a done roadmap row is not evidence > of merge-readiness: this gate still has to pass on its own. The two things this gate > most often catches on a done-but-unmerged unit are pending docs and a > prematurely-removed issue/fix-index entry — both are blockers.

Process

1. Gather — Step 0: project contract, PR, SPEC + artifacts, CI status.
2. Walk the contract — evaluate every gate above against evidence. For each,

record pass / blocker / n-a with the specific artifact or check that proves it.

1. Confirm deferrals are real — for anything postponed (an unchecked task, a

review finding, a known issue), verify a tracked issue + trigger exists. A deferral with no destination is a blocker, not a pass.

1. Decide — one verdict:

• MERGE-READY — every applicable gate passes; list the few things the human

should still eyeball (the manual-verification items review-change surfaced).

• BLOCKED — one or more gates fail; output the ranked blocker list.

1. Post the MERGE-READY comment on the PR (MERGE-READY only). The verdict

must be visible on the PR itself — as a comment, never in a commit message (a commit trailing "MERGE-READY" pollutes history and goes stale the moment the branch moves). Write the body to a file (Markdown rule — see Guardrails) and run gh pr comment --body-file with exactly this body:

```markdown

## ✅ audit-pr: MERGE-READY

• Audited head: `` · CI:
• Date:
• Before merge, a human should still verify:

Any commit after ` voids this verdict — re-run audit-pr. ``

Idempotent: first check the existing comments (gh pr view --json comments) for the `` marker — same SHA already commented → skip (say so); older SHA → post the new comment (the newest marker wins). Never post a comment for a BLOCKED verdict — blockers go in the chat report only, so the PR page never shows a stale green flag.

1. Auto-merge check (only on MERGE-READY) — evaluate the opt-in auto-merge

section below. Policy present + pre-merge checklist green → merge and report the merge evidence. Otherwise the human merges — say so explicitly.

1. Report — the verdict block below, always headed by the PR's full URL.

Auto-merge (opt-in — default is the human merges)

By default this skill never merges. It merges a MERGE-READY PR only when both keys hold:

1. Written authorization. The project's docs state the policy — e.g.

merge: auto / merge: fullauto in the agent guide's Workflow conventions or the committed decision record (docs/features/SHIP_DECISIONS.md) — or the user explicitly instructed it in this conversation ("merge it if merge-ready"). An inferred preference, a past session, or convenience is never authorization.

1. Pre-merge checklist — RUN it fresh, paste the outputs; fail-closed (any

box that cannot be evaluated counts as failed):

`` ✓ VERDICT is MERGE-READY, issued in THIS turn, bound to the PR's current head SHA (re-check the head via the forge — any later commit voids it) ✓ git status --porcelain → empty (nothing uncommitted — code or docs) ✓ git fetch + git status -sb (on the PR branch) → neither ahead nor behind its remote (nothing unpushed, nothing unpulled) ✓ Remote head SHA == the SHA this audit evaluated ✓ CI re-checked green on that exact SHA via the forge at merge time (no-CI project: a fresh local gate run on that SHA, output pasted) ✓ The PR touches no declared sensitive area and contains no destructive (data-deleting / schema-destructive) diff ✓ The forge accepts the merge (a refusal — branch protection, conflicts — parks the PR; never bypass, never force) ``

1. Anything pending → do NOT merge, even with authorization. Uncommitted or

unpushed work would make the PR's CI result stale the moment it lands. The sequence is fixed: route the pending work (commit + push via execute-phase's fold cycle) → wait for CI on the new head → re-run audit-pr → only a fresh MERGE-READY on the new SHA may merge. Never merge on a stale verdict.

After a successful merge: print the merged PR URL + merge SHA, and route the post-merge close-out (pull the default branch; remove/archive the fix-index entry per the project's convention — only now, never before).

Verdict format

PR # — 
URL: 
Base:  ← Head:  @    CI: 

VERDICT: MERGE-READY | BLOCKED ( blockers)

Blockers (ranked):
  1. []  — evidence: 
     → fix:  ()
  ...

Non-blocking nits:
  -  — 

Before merge, a human should still verify:
  - 

→ Next:
  · MERGE-READY, no auto-merge policy → you merge: , then
    /plan-feature --next (the next roadmap unit) or pick an issue with /triage-issue
  · MERGE-READY, auto-merge authorized → merged (URL + merge SHA above), then
    /plan-feature --next or /triage-issue
  · MERGE-READY but pending commit/push/pull found → NOT merged: commit + push,
    wait for CI, re-run /audit-pr (a fresh verdict on the new SHA decides)
  · BLOCKED → clear the top blocker (routed above), then re-run /audit-pr

If MERGE-READY, omit the blocker list and state it plainly: nothing blocks merge. The → Next: block is always printed — on MERGE-READY it repeats the full PR URL (merge it yourself, or the merged link) and points the user at the next concrete unit so a finished feature never dead-ends at the merge.

Example (generic — substitute your project's numbers and gates):

PR #142 — Add CSV export to the reports view
Base: main ← Head: feat/14-csv-export   CI: green

VERDICT: BLOCKED (2 blockers)

Blockers (ranked):
  1. [Tests] Export handler has no test — acceptance criterion "export
     round-trips the rows" is unverified
     → fix: add an integration test for the handler (fold into the current phase)
  2. [Traceability] PR body is missing `Closes #131` for issue-born work
     → fix: add `Closes #131` to the PR body (execute-phase)

Non-blocking nits:
  - Help text wording diverges from the other commands — docs/USAGE.md

Before merge, a human should still verify:
  - The exported file opens cleanly in a spreadsheet app (visual)

Routing (blockers, by kind)

• Incomplete in-scope work → fold into this branch via execute-phase

(the relevant phase or --fix); re-run audit-pr after.

• Out-of-scope defect surfaced → plan-fix (new fix entry), not this PR.
• Deferred finding lacking a home → triage-issue to file + classify it.
• Stale/missing docs → update per the doc map (often a quick execute-phase

doc commit), then re-audit.

• Red CI / failing gate → report the failing check; the dev fixes on-branch.

Guardrails

• Read-first verdict. Never push, edit, or refactor. The only forge writes

this skill may perform: (1) the MERGE-READY comment (Process step 5 — idempotent, comment-only, never a commit tag), and (2) the opt-in auto-merge — written policy or explicit instruction, MERGE-READY on the current SHA, pre-merge checklist green, outputs pasted. One key missing → the human ships.

• Forge bodies are Markdown, not shell — never hand-escape. The comment's

backticks are formatting; a \ before them renders literally. Write the body to a file and pass --body-file — never inline --body "…" or a quoted heredoc. Verify with gh pr view --json comments that no literal ` \ `` survived.

• Never merge with anything uncommitted, unpushed, or unpulled — even when

auto-merge is authorized. Pending work makes the CI evidence stale: commit + push, wait for CI, re-audit, and only the fresh verdict may merge.

• Never report MERGE-READY on an unconfirmed gate — absence of evidence is a blocker.
• Don't re-run the full review from scratch; compose review-change and verify its

open findings are resolved or tracked.

• Honor the project's Workflow conventions (gate, docs-language, evidence —

every blocker cites file:line/check/criterion/issue — track-don't-inline: out-of-scope problems become issues/fix entries, never silent additions here).

Machine envelope

Every invocation ends with the machine envelope — schema, field rules and placement per the installed orchestration-envelope skill: one fenced

``json block, printed **after** the closing block above, as the **absolute last output** of the turn (external orchestrators parse the LAST fenced json block; see docs/workflow/ORCHESTRATION.md`). All top-level keys always present; values only from verified command output, never invented.

This skill emits:

• state: MERGE_READY (verdict MERGE-READY; the PR comment below was

posted; pr.merge_ready: true), MERGED (opt-in auto-merge executed — merge SHA in detail), NEEDS_FIXES (in-scope blockers → fold on-branch, re-audit; blockers[] mirrors the ranked list), or BLOCKED (external cause: wrong base, conflicts, a dependency PR).

• Fields: pr fully filled (number, url, headsha, ci, mergeready);

gates.audit_pending: false after a verdict; findings.issues_filed = issues opened for deferrals lacking a home.

• detail: `{"verdict": "MERGE-READY|BLOCKED", "blockers_ranked": [...],

"manualverification": [...], "mergesha": ""}`.

Example (MERGE-READY, default mode — abbreviated):

{"skill": "audit-pr", "state": "MERGE_READY",
 "summary": "PR #14 passes every gate; comment posted; human merges.",
 "unit": {"type": "fix", "id": "43-null-crash", "issue": 43, "branch": "fix/43-null-crash"},
 "phase": {"current": null, "total": null, "completed": null},
 "pr": {"number": 14, "url": "https://github.com/o/r/pull/14", "state": "open",
        "head_sha": "abc123", "merge_ready": true, "ci": "green"},
 "gates": {"verification": "green", "review_pending": false, "audit_pending": false},
 "findings": {"fix_now": [],

…

## Source & license

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

- **Author:** [gtrabanco](https://github.com/gtrabanco)
- **Source:** [gtrabanco/agentic-workflow](https://github.com/gtrabanco/agentic-workflow)
- **License:** MIT

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