From 6a25898bfe2ee4b7978e8d8f796fd1e34797efac Mon Sep 17 00:00:00 2001 From: atlas Date: Fri, 26 Jun 2026 00:29:56 +0200 Subject: [PATCH] docs(forge): add a 'which read verb when' selection table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of the #1802 hive-forge audit: the read verbs (view / issue / pr / comments / comment-show / timeline / diff / pr-status / pr-reviews) look overlapping but each has a distinct output shape. Add a selection table + rule-of-thumb so agents pick the right one (esp. 'view first' to clear the read-before-comment guard) instead of guessing. Zero blast radius — pure docs, no verb changes (the audit concluded the CLI is structurally clean and renames/removals aren't worth the caller breakage). --- docs/tools/forge.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/tools/forge.md b/docs/tools/forge.md index cde6a0fc..1cd9e08b 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -86,6 +86,27 @@ hive-forge -r internal/knowledge clone # clone with creds auto-injected hive-forge -r internal/knowledge pr-create --agit --topic foo --title "..." # open PR via AGit (no fork) ``` +### Which read verb when + +Several verbs read an issue/PR and look overlapping, but each has a +distinct output shape — pick by what you need: + +| Need | Verb | Shape | +|------|------|-------| +| The full human view of one item — title, body, **and** every comment in order | `view ` | prose dump; **marks the thread read** (clears the read-before-comment guard) | +| Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue ` / `pr ` | JSON object | +| Only the comments (skip the body), e.g. to catch up a long thread | `comments ` [`--tail N`] | comment list; **marks read** | +| One specific comment by its id | `comment-show ` | single comment | +| The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline ` | event list | +| The code change | `diff ` | unified diff | +| Is this PR ready to merge — mergeable + CI + reviews | `pr-status --pr ` | health view; exit code = merge-readiness | +| The review verdicts + inline review comments | `pr-reviews ` | review list | + +Rule of thumb: **`view` first** when you're about to act on a thread (it +shows everything and clears the unread guard so your follow-up `comment` +isn't rejected); the JSON verbs (`issue`/`pr`) when a script needs one +field; `pr-status` when the only question is "can I merge it". + ### Contributing to a read-only repo (`clone` + `pr-create --agit`) Agents are read-only collaborators on some repos (e.g.