docs(skills): document post-PR review contract in publish skill (#1163)

22cc006fb9c3a2257d72ef75f3637e37aaa1aea5 · 2026-05-12 00:01:38 -0700 · Trevin Chow

* docs(skills): document post-PR review contract in publish skill

When an agent runs /printing-press-publish from cli-printing-press, it
never loads the public library's AGENTS.md and so misses the contract
to drive the PR through Greptile review and CI before merge. Add an
"After the PR opens" section that summarizes the obligation inline
(resolve every finding, all CI checks green, no merging with open
threads, no hand-edits to bot-regenerated files, hand off when
review-ready) and points to the library AGENTS.md for the canonical
version.

The Greptile framing matches the matching softening in
mvanhorn/printing-press-library#490: the 0-5 score is a confidence
signal, not a hard gate; 4/5 and 5/5 are both acceptable end states
that follow naturally once threads are addressed.

* docs(skills): include inline review comments in publish skill retrieval

Greptile P1 finding on #1163: gh pr view --comments returns only the
top-level issue conversation, not the diff-anchored inline review
comments where Greptile posts each P0/P1/P2 finding. An agent following
the prior wording would see the summary and miss every inline thread.

Verified empirically on this PR: --comments returned 2 top-level
comments (Mergify, Greptile summary) and 0 inline threads;
gh api .../pulls/1163/comments returned the 1 P1 finding anchored to
SKILL.md:894.

Update the prose to require both calls with an explicit note that the
inline comments are NOT included in --comments, so the next agent
doesn't drop the second call as redundant.

Files touched

M skills/printing-press-publish/SKILL.md

Diff

commit 22cc006fb9c3a2257d72ef75f3637e37aaa1aea5
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Tue May 12 00:01:38 2026 -0700

    docs(skills): document post-PR review contract in publish skill (#1163)
    
    * docs(skills): document post-PR review contract in publish skill
    
    When an agent runs /printing-press-publish from cli-printing-press, it
    never loads the public library's AGENTS.md and so misses the contract
    to drive the PR through Greptile review and CI before merge. Add an
    "After the PR opens" section that summarizes the obligation inline
    (resolve every finding, all CI checks green, no merging with open
    threads, no hand-edits to bot-regenerated files, hand off when
    review-ready) and points to the library AGENTS.md for the canonical
    version.
    
    The Greptile framing matches the matching softening in
    mvanhorn/printing-press-library#490: the 0-5 score is a confidence
    signal, not a hard gate; 4/5 and 5/5 are both acceptable end states
    that follow naturally once threads are addressed.
    
    * docs(skills): include inline review comments in publish skill retrieval
    
    Greptile P1 finding on #1163: gh pr view --comments returns only the
    top-level issue conversation, not the diff-anchored inline review
    comments where Greptile posts each P0/P1/P2 finding. An agent following
    the prior wording would see the summary and miss every inline thread.
    
    Verified empirically on this PR: --comments returned 2 top-level
    comments (Mergify, Greptile summary) and 0 inline threads;
    gh api .../pulls/1163/comments returned the 1 P1 finding anchored to
    SKILL.md:894.
    
    Update the prose to require both calls with an explicit note that the
    inline comments are NOT included in --comments, so the next agent
    doesn't drop the second call as redundant.
---
 skills/printing-press-publish/SKILL.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/skills/printing-press-publish/SKILL.md b/skills/printing-press-publish/SKILL.md
index fa1cba9a..467898c3 100644
--- a/skills/printing-press-publish/SKILL.md
+++ b/skills/printing-press-publish/SKILL.md
@@ -887,6 +887,20 @@ rm -f "$PR_BODY_FILE"
 
 Display the full PR URL (e.g., `https://github.com/mvanhorn/printing-press-library/pull/10`), not the shorthand `org/repo#N` format. The full URL is clickable in all terminals and contexts.
 
+## After the PR opens
+
+Once the PR is open, it enters the public library repo's review contract. That contract is owned by [`mvanhorn/printing-press-library` AGENTS.md → "Automated code review with Greptile"](https://github.com/mvanhorn/printing-press-library/blob/main/AGENTS.md#automated-code-review-with-greptile); read it for the canonical version. An agent invoking this skill from `cli-printing-press` will not have loaded the library's AGENTS.md, so the obligations are summarized here:
+
+- **Resolve every Greptile finding.** Read findings from two surfaces — they don't overlap:
+  - `gh pr view <PR> --repo <owner>/<repo> --comments` returns the top-level issue conversation (Greptile's summary comment, score, CI bots).
+  - `gh api repos/<owner>/<repo>/pulls/<PR>/comments` returns the inline diff-anchored review comments — Greptile posts each P0/P1/P2 finding here, **and these are NOT included in `--comments`**. Skipping this call is how an agent silently declares "all findings resolved" while every inline thread is still open.
+
+  For each P0/P1/P2 thread, either push a fix or reply with a concrete reason it shouldn't fire — not "won't fix", but *why* the code is right as written or *why* deferral is justified. The 0-5 score is a confidence signal, not a hard gate; 4/5 and 5/5 are both acceptable end states, and the score will land in that range naturally once threads are addressed.
+- **All CI checks must pass.** `verify-library-conventions`, `Govulncheck`, and any other workflow on the PR must be green before merge.
+- **Don't merge with unresolved threads** even when CI is green and the score looks good.
+- **Don't hand-edit `registry.json` or `cli-skills/pp-<api-slug>/SKILL.md` to satisfy a finding** — both are bot-regenerated post-merge by `[skip ci]` commits and your edits will be overwritten.
+- **Hand off once review-ready.** When all threads are resolved or replied to and CI is green, stop and tell the user. Don't loop polling for the merge; the user owns that decision.
+
 ## Secret & PII Protection
 
 Before creating the PR, verify that no secrets leaked into the packaged CLI.

← 88c5b696 feat(skills): add native code review phase to printing-press · back to Cli Printing Press · chore(main): release 4.5.0 (#1134) 12964486 →