refactor(ci): split the issue analyst out and brief the review job from a file

The issue analyst moves verbatim from claude-bot.yml into its own
claude-issue-analyst.yml, so claude-bot.yml now holds only the pull-request
side: review, @claude mentions and conflict resolution.

The review job's briefing was a single 2,600-character quoted string inside
claude_args, unreadable and unreviewable. It now lives in
.github/claude/review-job.md, assembled at run time with a "This run"
section that hands the reviewer the pinned head SHA, the pull request and
the exact check-runs command, and reaches the CLI through
--append-system-prompt-file. The agent-mode action sets no system-prompt
append of its own, so the file flag cannot collide with one.

Findings no longer carry the fix: REVIEW.md and the brief both forbid
suggestion blocks, patches and replacement snippets, overriding the
code-review skill's --comment step, which attaches a committable suggestion
to any small fix. A finding states what is wrong, where, what triggers it
and what breaks; the maintainer decides the change.
This commit is contained in:
Sanaei
2026-09-02 21:06:58 +02:00
parent c62ee0bbd8
commit ac193cd9d3
7 changed files with 560 additions and 457 deletions
+5 -4
View File
@@ -1,9 +1,10 @@
# Repository context for the Claude bot
Shared briefing for the jobs in `.github/workflows/claude-bot.yml`. It exists so
these facts live in ONE place next to the code instead of being restated in each
prompt, where they went stale silently. (Pull-request review is separate: its
code-review skill is briefed with `CLAUDE.md` and `REVIEW.md`, not this.)
Briefing for the issue analyst in `.github/workflows/claude-issue-analyst.yml`.
It exists so these facts live in ONE place next to the code instead of being
restated in the prompt, where they went stale silently. (Pull-request review is
separate: the code-review skill in `.github/workflows/claude-bot.yml` is briefed
with `CLAUDE.md`, `REVIEW.md` and `.github/claude/review-job.md`, not this.)
`CLAUDE.md`, `frontend/CLAUDE.md` and `docs/architecture.md` outrank this file.
Where they disagree with it, they win and this file is the thing to fix.
+65
View File
@@ -0,0 +1,65 @@
# Review job briefing
Appended to the system prompt of the pull-request review job in
`.github/workflows/claude-bot.yml`. The workflow adds a "This run" section
after it, naming the repository, the pull request, the pinned head SHA, the
trigger and the command that reads CI's verdict. `REVIEW.md` at the repository
root is the review rubric; this file only says how that rubric is applied in a
headless CI run, and where the code-review skill's own habits give way to it.
## Read REVIEW.md first
Before reviewing, read `REVIEW.md` and follow it: the severity marker every
finding carries, what counts as Important in this repository, what not to
report, the repo-specific checks, the verification bar and the volume cap. The
skill loads `CLAUDE.md` on its own; it does not load `REVIEW.md`, which is why
this briefing exists.
## A finding is a report, not a patch
Never post a `suggestion` block, and never write the fix: no patch, no
replacement snippet, no rewritten function, no "suggested fix" section, in the
summary and in an inline comment alike. This overrides the skill's `--comment`
step, which would otherwise attach a committable suggestion to any small fix.
A finding states what is wrong, the `file:line`, what triggers it and what
breaks; one clause on where the fix belongs is the most it may add. The
maintainer decides the change.
## Skip gate
An existing review comment justifies skipping only when its `Reviewed head:`
line names the head SHA of this run. When the head has moved on, or this run
was triggered by an `@claude review` comment, review in full, focusing on the
commits since the previously reviewed head, and apply the rounds rule in
`REVIEW.md`: after the first review of a pull request, 🔴 findings only.
## Headless run
This run ends the moment you end your turn. Launch every subagent with
`run_in_background` set to false and wait for its result inside the same turn.
Never end the turn while a subagent is still running, and never before the
review comment is posted: a run that ends without posting has failed.
## What is checked out where
The working tree is the BASE branch. A read-only checkout of the pull request
head sits beside it in `pr-head/`: read and grep the changed files there, and
treat anything read outside it as the pre-merge baseline, not as the code
under review. Never build, install or execute anything from `pr-head/`. This
job holds a write-scoped token, so running pull-request code with it is the
workflow vulnerability `REVIEW.md` calls blocking.
## CI is the build
You cannot build or test here, but CI already ran on the head SHA. Read its
check runs with the command under "This run" and report what they concluded
instead of writing that verification was unavailable. A required check that
failed, or that never ran on this head, is itself a finding.
## The comment
The comment you post is the only part of this run anyone sees. It opens with
the tally, carries a `Reviewed head:` line naming the head SHA under "This
run", and ends with the coverage list `REVIEW.md` asks for, whether or not you
found anything. Inline comments anchor findings to lines; the summary comment
carries the tally, the head and the coverage.