buhtig 0.1.0-alpha.1

package/packages/cli/dist/docs/buhtig-review/SKILL.md

@@ -0,0 +1,124 @@
+# buhtig-review
+
+Focused facet reviewers fan out over the repo's own taxonomy; each writes its findings to buhtig as
+structured rows — scored, anchored to `(path, line)`, and triaged by the human in the Review tab.
+
+{{preamble}}
+
+The rest of this skill is four more documents, fetched the same way you fetched this one:
+**`ORCHESTRATOR`** (the run lifecycle), **`FACET_REVIEWER`** (the brief a facet subagent gets),
+**`API`** (every call, in the order a run uses them), **`PROVENANCE`** (a separate job with its own
+brief).
+
+## What buhtig does for you, that you must not do yourself
+
+| | Owner |
+|---|---|
+| The facet taxonomy, the contract, per-facet briefs | **buhtig** — read the review config. Never hardcode a facet list. |
+| Anchor fingerprints, snippets, blob OIDs, staleness | **buhtig** — you send `path` + `line`, nothing more. |
+| Whether a line is postable to GitHub (`inHeadDiff`) | **buhtig** — computed against the real diff. |
+| Rendering cited code — real diff, line numbers, expandable context | **buhtig** — label a snippet `buhtig-diff:<path>#L84-L96` and it becomes the real thing. See `FACET_REVIEWER`. |
+| `F<N>` numbering | **buhtig** — at synthesis, after every facet has reported. |
+| Deciding what is dismissed, what goes to the author, what gets a ticket | **the human.** You can set those marks, and only when they ask you to — see `API` §10. |
+| Turning a staged finding into a draft PR comment | **buhtig** — staging composes it; you never write one by hand. |
+| Prose, scores, `(path, line)`, the assignment bookkeeping | **you** |
+
+## Execution outline
+
+1. **Identify scope** — changed files, ticket + acceptance criteria, touched product domains, and the
+   PR head SHA (`gh pr view <n> --json headRefOid`).
+2. **Start the run** with a `runKey` and that `headSha`. You get the run id and one **assignment** per
+   reviewable facet. Re-using the same `runKey` resumes — it never forks. A repo that has declared no
+   `subagentBudget` is refused here with a 422: report it and stop, rather than reviewing some other
+   way. What a review costs is the human's call, not yours.
+3. **Commission the briefing** — one comprehension agent over the changed surface, stored on the run.
+   A factual map, no findings. Every facet agent reads it instead of re-deriving the same call graph
+   for itself.
+4. **Pack the applicable assignments into bundles** — as many as `config.subagentBudget` allows — and
+   dispatch one subagent per bundle. Each is handed *only* its own facets' briefs, the briefing, and
+   `FACET_REVIEWER`. Mark the ones you deliberately skip `status: skipped` **with a reason** — a facet
+   nobody looked at must not read like a facet that came back clean.
+5. **Each subagent** updates each assignment's status, stores its report, and writes its findings.
+   They write directly; you do not funnel their prose through your own context.
+6. **Synthesize.** Read the current dispositions first — the human triages while the run is still in
+   flight, and you must never write over a resolution you did not set. Then deduplicate across facets
+   (merge with `mergedIntoSlugId`), set `section` on the findings that belong in the summary, write
+   the run's `recommendationMd` / `summaryMd` / `reviewerNotesMd`, then synthesize to assign `F<N>`.
+7. **Complete the run** and report a terse chat summary — the verdict, the blocker count, and the
+   coverage gaps. Do not paste the findings into chat; they are queryable.
+8. **Stay reachable.** Tell the human where the review is — disposition and posting are theirs — and
+   keep watching for their inline messages, on the run **and** on the PR. Completing the run does not end
+   that; see `ORCHESTRATOR` §8.
+
+## If buhtig started you
+
+`$BUHTIG_AGENT_CONTEXT` names a briefing file, and it carries **the exact command that watches the
+channel** — one command, already pointed at this worktree's subjects and already carrying your
+identity. Read the briefing before anything else: it is how you learn that the human can talk to you
+at all. Nothing interrupts you when they do — the message waits on the channel until you look.
+
+## Scoring
+
+The scales come from the review config, **each level carrying its own definition** — read
+`severities` and `priorities` off `review.config` and score against the `title`/`hint` they ship
+with, rather than against what `P1` means in some other project. A repo may drop levels, reorder
+them, or replace a `hint` with its own risks; it never has to restate the scale to use it.
+
+- `severity` `P0`–`P4` — impact if the finding is real.
+- `reviewPriority` `R0`–`R3` — how deeply the dimension was reviewed. `priorityNote` carries an
+  escalation ("R1 (escalated — persisted data)").
+- `confidence` `high` | `medium` | `low` — **shown to the author**, on its own line of the composed
+  author-facing body, and editable by the human. Uncertainty stated plainly invites a correction; the
+  same finding with the hedge stripped reads as an assertion the author has to disprove.
+- `blocking` — does it block merge.
+- `audience` `reviewer` | `agent-internal` | `author` | `reviewer+author`. Reviewer-only findings
+  cannot be staged without a logged human override, which is the point.
+
+## The three prose parts
+
+`bodyFinding` (the concrete issue) · `bodyWhy` (impact if true) · `bodyFix` (actionable) —
+identifier-led, example-heavy.
+
+**What the author reads is composed, not written.** buhtig builds it from `title`, `bodyFinding` and
+`bodyFix`, led by `**[blocker · P1] <title>**` and a `_Confidence: High_` line. `bodyAuthor` is
+read-only — there is no author-facing copy to keep in sync, so a correction to the three bodies is the
+only correction there is.
+
+`bodyWhy` is reviewer-only. It argues impact to a reviewer deciding whether the finding matters, a
+decision the author is not making. To keep a whole finding off the author's screen, use
+`audience: reviewer`.
+
+## Writing style
+
+Follow the `/writing` skill: terse, top-down, no fluff. Identifier-led and example-heavy — pin the
+real symbols and a laser-focused example (a snippet, an input→wrong-output pair, the query missing its
+filter) and let those carry the finding. **No praise** in anything author-facing.
+
+Markdown prose is stored verbatim and rendered in a browser, so:
+
+- **Do not hard-wrap.** One physical line per paragraph or list item.
+- Link code as ``[`symbol`](path/to/file.ts#L120)`` with **repo-relative** paths — buhtig rewrites
+  them into deep links. Do not write `../../` prefixes; there is no file to be relative to.
+
+## Follow-up tickets
+
+Opt-in, and the human's. They compose the tickets in the Outbox — grouping findings, editing the
+bodies, arranging the hierarchy — and mark the ones they want filed `ready`.
+
+Your part is filing what is already composed, and only when asked:
+
+```call ticket.list
+{ "status": "ready" }
+```
+
+…file it in the tracker, then record where it landed:
+
+```call ticket.update
+{ "id": "$TICKET_ID", "status": "filed", "url": "https://linear.app/…", "externalKey": "WEB-1235" }
+```
+
+That one write flips every member finding to `ticketed` with the URL. See `API` §10.5.
+Never mark a ticket `ready`, and never open one unprompted.
+
+Add **one** session todo — "tally follow-ups before closing the review for PR #N" — pointing at the
+`followup=wanted` findings, the Outbox, and any unresolved PR threads.