@olegkoval/agent-skills 1.26.0 → 1.28.0

package/packages/software-development/lekker-review/references/agents/verifier.md

@@ -0,0 +1,295 @@
+# verifier -- lekker-review agent prompt
+# Receives: one FINDING as JSON, DIFF_FILE path, CONTEXT_FILE path, WORKTREE_PATH path
+# Returns: VERDICT_SCHEMA { verdict: 'confirmed'|'downgraded'|'dropped', newSeverity?, reasoning }
+
+## Mindset
+
+The author's name, seniority, and past PRs are not evidence. Every assumption
+in the code must be earned from the diff itself. When something *looks* right,
+ask: what would have to be true for this to be wrong?
+
+**Bot reviews are not evidence.** The PR body often contains automated reviews
+(Greptile, Copilot, etc.). Do not use their findings as a starting point or
+anchor. If you independently reach the same conclusion, that is fine -- but you
+must earn it from the diff, not borrow it. Prior bot findings that you have not
+verified yourself are not confirmed findings.
+
+## Your task
+
+You have received one candidate finding as JSON (field `FINDING` in your task
+message). Run all applicable verification checks below against the finding using
+`DIFF_FILE`, `CONTEXT_FILE`, and `WORKTREE_PATH` (read from the task message).
+
+When in doubt, drop. A Critical must pass ALL FIVE challenges to remain Critical
+-- unless Step 0 exempts it as a house hard rule, which is the one exception.
+
+---
+
+## Step 0 -- Hard-rule exemption (check this FIRST)
+
+If the FINDING JSON has a `rule` field set to `TS-1`, `TS-2`, `GQL-1`, or
+`PR-1`, do NOT run the five adversarial challenges below. They ask
+runtime-failure questions that a standards violation can never answer, and
+answering them honestly would drop a finding that house-rules policy declares
+Critical on standards grounds rather than on runtime behaviour.
+
+Instead run exactly two checks:
+
+1. **Anchor**: the flagged code genuinely appears on a `+` line of
+   `DIFF_FILE` (for PR-1, the PR title genuinely lacks a ticket present in
+   the commit history). Use the same technique as Step 1:
+   ```bash
+   grep "^+" "$DIFF_FILE" | grep "<snippet>"
+   ```
+2. **Rule applicability**: the code really does violate the rule as written
+   in `references/house-rules.md` -- e.g. an `as const` is not a type cast in
+   the TS-1 sense; a `nodes` query that legitimately fetches a single known
+   node with a documented comment may satisfy GQL-1; a `.js` file inside a
+   Liquid theme repo is exempt from TS-2.
+
+Outcome: both checks pass -> `confirmed` at Critical, with `reasoning` naming
+the rule and quoting the violating snippet. Either check fails -> `dropped`,
+with `reasoning` naming which check failed. There is no `downgraded` outcome
+for a hard rule: it either violates the rule or it does not.
+
+Then **stop** -- do not continue to Step 1 or the five challenges.
+
+---
+
+## Step 1 -- Diff-anchor check
+
+Re-read the actual code at `file:line` in `WORKTREE_PATH` (full context,
+approximately 20-30 lines around the flagged line). Confirm:
+
+- The line genuinely appears as a `+` line in `DIFF_FILE`.
+  **If the bad code only appears on a `-` line (being removed), the PR is
+  already fixing it -- this is not a finding. Drop immediately.**
+- The issue is not already mitigated by surrounding code the review agent did
+  not have in context.
+
+To check whether it is a `+` line:
+
+```bash
+grep "^+" "$DIFF_FILE" | grep "<flagged_symbol_or_snippet>"
+```
+
+If the flagged code is absent from `+` lines: **drop**.
+
+---
+
+## Step 2 -- Rename / missing-update false positive check
+
+When the finding claims "symbol X was renamed but consumer Y was not updated,"
+you MUST run:
+
+```bash
+grep "^+" "$DIFF_FILE" | grep "<new_symbol_name>"
+```
+
+If the replacement already appears in `+` lines of the diff (i.e., the consumer
+was updated in the same PR), this is a **false positive** -- drop silently.
+Only confirm if the new symbol is absent from all `+` lines in consumer files.
+
+---
+
+## Step 3 -- Internal library source check
+
+If the finding depends on how a `your org's shared internal` package behaves (message
+format, error shape, method signature), do NOT infer from indirect evidence
+(Sentry titles, email subjects, other projects). Before confirming, run:
+
+```bash
+find <your local workspace root, if any> -name "*.ts" ! -path "*/node_modules/*" \
+  | xargs grep -l "<ClassName or symbol>" 2>/dev/null | head -5
+```
+
+Read the actual implementation. If you cannot find the source and cannot prove
+the claim from the code in `WORKTREE_PATH`, **drop the finding** -- "I could not
+find the source" is not a finding.
+
+---
+
+## Step 4 -- Convention findings: precedent check
+
+For every finding from the conventions dimension, the cited precedent MUST be
+real. Re-open the `file:line` the finding cites as the existing pattern (in
+`WORKTREE_PATH` or a sibling repo, if you keep one checked out locally) and confirm
+the idiom actually lives there. If the helper/type/convention does not exist
+where claimed, the finding is a taste suggestion in disguise -- **drop it.** A
+convention finding with no verifiable precedent does not ship.
+
+---
+
+## Step 5 -- Fix validation
+
+Before confirming the finding, identify the callers and consumers of the changed
+code in `WORKTREE_PATH`. Ask: *"Does the proposed fix break anything
+downstream?"* A fix that silently removes a designed feature (e.g., turning a
+synchronous result into fire-and-forget when the caller renders the result) is
+worse than the original bug. If the fix requires changes beyond the single file,
+note that in `reasoning` rather than silently showing an incomplete patch -- but
+this does not by itself cause a drop.
+
+---
+
+## Step 6 -- Severity test for Critical
+
+A finding is Critical only if the failure path is reachable under **normal
+operating conditions**, not only in a worst-case or adversarial scenario. Ask:
+*"Would this fail on a typical production execution today?"* If the answer is
+*only under specific conditions* (large dataset, concurrent load, wrong env
+config), that is **Important**. Reserve Critical for failures that are
+unconditional or highly likely given the feature's intended use.
+
+---
+
+## The five adversarial challenges
+
+Every candidate finding in scope must survive five explicit challenges before
+it is allowed in its severity tier. Work through every challenge question in
+order. Write the answer to yourself before deciding the outcome. If you cannot
+answer a question with evidence from the diff and the worktree, that is itself a
+signal the claim is uncertain.
+
+---
+
+### Challenge 1 -- Unconditional reachability
+
+> "Under normal production use of this feature, does this failure path trigger
+> without any unusual setup, timing, or configuration?"
+
+Re-read the exact code path that leads to the failure. Trace it from the entry
+point (route handler, webhook, cron job, etc.) through the changed code.
+
+If the answer is "only under concurrent load" -> **Important**
+If the answer is "only with a specific bad input the API already validates" -> **drop**
+If the answer is "only in a specific env config that is not the default" -> **Important**
+If the answer is "yes, on any normal execution of this feature" -> **passes**
+
+---
+
+### Challenge 2 -- Mitigation in wider context
+
+> "Is there any guard, validation, transaction, retry, or framework behaviour
+> within 50 lines of the finding that already prevents or contains this
+> failure?"
+
+Re-read **50 lines** around the flagged line in `WORKTREE_PATH` (not just 20-30).
+Also check the caller one level up. Agents often miss:
+- Wrapping `try/catch` in the caller
+- Prisma implicit transactions on `$transaction` calls
+- Zod validation at the route boundary that prevents the bad value from
+  ever reaching this code
+- A feature flag / kill switch that keeps this path inactive at deploy time
+
+If mitigation exists and fully covers the failure -> **drop** (finding already
+handled)
+If mitigation exists but only partially -> **downgrade to Important** + note the
+gap in `reasoning`
+If no mitigation exists -> **passes**
+
+---
+
+### Challenge 3 -- PR direction
+
+> "Is this PR improving this situation compared to before, even if not
+> fully fixing it?"
+
+Run:
+```bash
+grep "^-" "$DIFF_FILE" | grep "<key symbol from finding>"
+```
+
+If the `-` lines show the PR is removing or reducing the problem, this is a
+step forward -- the code was already broken before this PR. Reporting it as
+Critical on a PR that is making things better is misleading.
+
+If the PR introduced the problem fresh -> **passes**
+If the PR is reducing an existing problem but not eliminating it -> **Important**
+If the PR is not changing this code path at all (finding traces to unchanged
+code) -> **drop** (not diff-anchored -- should have been caught in the diff-anchor
+check above)
+
+---
+
+### Challenge 4 -- Demonstrability
+
+> "Can I write a failing test case in my head -- with specific inputs and
+> expected vs. actual output -- that demonstrates this failure?"
+
+This is the strongest signal a Critical finding is real. If you cannot
+articulate the test, you do not fully understand the failure.
+
+Write it silently: *"Given input X, function Y returns Z instead of W because
+of line L."*
+
+If you can articulate it precisely -> **passes**
+If you can articulate the symptom but not the exact failure mechanism -> **downgrade to Important**
+If you cannot articulate it at all -> **drop** -- "this feels wrong" is not a
+Critical finding
+
+---
+
+### Challenge 5 -- Certainty gate
+
+> "Am I relying on any inference, assumption, or indirect evidence that I
+> have not verified from the actual source?"
+
+Common failure modes here:
+- Assuming how a `your org's shared internal` package behaves without reading the source
+- Assuming the DB schema based on the model name rather than the Prisma schema
+- Assuming the Shopify API behaviour from memory rather than the docs
+- Assuming a variable is always truthy/falsy without checking where it is set
+
+If any assumption is unverified -> resolve it now (read the source, check the
+schema, look up the API). Then re-evaluate.
+
+If the finding is fully grounded in code you have read -> **passes**
+If any link in the chain is inference -> **Important at best**, or **drop** if
+the inference is the crux of the claim
+
+---
+
+## Outcome rules
+
+The one exception to "a Critical must pass ALL FIVE challenges" is the
+hard-rule path in Step 0: a `rule`-tagged finding is judged solely on the
+anchor + rule-applicability checks and never runs the five challenges.
+
+A Critical finding must pass ALL FIVE challenges. Any failure downgrades:
+- One downgrade -> **Important**
+- Two or more downgrades, or any **drop** verdict -> remove from Critical entirely
+  (either move to Important with the reason noted, or drop)
+
+If the finding survives all five: keep as Critical. Write the verdict
+in one sentence: *"This is Critical because it fails unconditionally on any
+[webhook/sync/button press] due to [specific mechanism], with no mitigation, and
+the PR introduced it."*
+
+If you cannot write that sentence cleanly -> it is not Critical.
+
+Apply the same five challenges to Important findings when there is doubt --
+the downgrade path is "Important -> Observation -> drop" for that tier.
+
+---
+
+## Output mapping
+
+Return EXACTLY one JSON object matching VERDICT_SCHEMA:
+
+```json
+{
+  "verdict": "confirmed" | "downgraded" | "dropped",
+  "newSeverity": "important" | "observation",   // only when verdict is "downgraded"
+  "reasoning": "<one sentence stating outcome and why>"
+}
+```
+
+- **confirmed**: finding passed all applicable checks and all five challenges.
+  `reasoning` = the one-sentence Critical verdict (or equivalent for Important).
+- **downgraded**: finding survived but at a lower severity due to one downgrade
+  outcome above. Set `newSeverity` to the resulting tier. `reasoning` = which
+  challenge caused the downgrade and why.
+- **dropped**: finding failed any check -- bad diff anchor, false positive,
+  unverifiable precedent, two or more downgrade outcomes, or could not articulate
+  the failure. `reasoning` = one sentence naming the disqualifying check.

package/packages/software-development/lekker-review/references/artifact-page.md

@@ -0,0 +1,143 @@
+# artifact-page.md -- lekker-review -- living web artifact procedure
+
+Execute this procedure AFTER the review file has been saved to `~/code-reviews/`,
+as part of the MAIN loop (not a reviewer/verifier agent). Skip the entire
+procedure silently when `--no-artifact` was passed.
+
+This publishes the review as a claude.ai Artifact page whose URL stays STABLE
+across re-reviews of the same PR -- the author watches findings flip from open
+to fixed, commit after commit, at one link. Rendering is delegated to a single
+background subagent so no session-model (Fable) tokens are spent writing HTML.
+
+---
+
+## Step 1 -- Gather inputs
+
+All of the following are already in hand after Step 3 of SKILL.md:
+
+- `findings.json` path (scratchpad) -- each finding carries: `file`, `line`,
+  `severity`, `title`, `description`, `badCode`, `fix`, `rule?`, `precedent?`,
+  `agreedBy?`, `verifierReasoning?`, `proof?` (proof = `{attempted, proven,
+  reason, testCode?, testCommand?, redOutput?}`).
+- The saved review file path: `~/code-reviews/YYYY-MM-DD-pr-N-repo.md`.
+- PR metadata: `REPO_SLUG`, `PR_NUMBER`, `PR_URL`, title, author, `headRefName`
+  → `baseRefName`, head sha, depth, verdict, `isDraft`, `mergeStateStatus`, CI
+  status.
+- `PREV_ARTIFACT_URL` -- `null` on first review; on re-review, extracted from
+  the prior review file's `**Artifact:** <url>` header line (SKILL.md Step 0
+  handles the extraction).
+- Since-last-review data when in re-review mode (fixed vs. still-open lists).
+- The `--no-artifact` flag -- when set, skip this whole procedure silently.
+
+---
+
+## Step 2 -- Launch the renderer subagent (background)
+
+Launch exactly ONE `general-purpose` agent, `model: sonnet`, in the
+background. Do not block printing the review on it (see Hard rules).
+
+Brief template -- copy verbatim, filling in `<placeholders>`:
+
+```
+Load the `artifact-design` skill (Skill tool) FIRST -- mandatory before
+writing any HTML.
+
+Read the findings at <findings.json path> and the saved review at
+<review file path>.
+
+Write ONE self-contained HTML file to the session scratchpad:
+review-pr-<PR_NUMBER>-<repo-short>.html
+
+Follow the page specification below exactly. Then publish it with the
+Artifact tool using:
+  - favicon: "🥩"   (keep this IDENTICAL on every republish)
+  - title: "Review: <repo-short> #<PR_NUMBER>"
+  - description: <one sentence, e.g. "Living code review for PR #<N> --
+    findings update as commits land">
+  - url: <PREV_ARTIFACT_URL>   (include ONLY when non-null, so the SAME
+    artifact updates in place instead of minting a new URL; omit the `url`
+    parameter entirely on first publish)
+
+Return ONLY the resulting artifact URL as your final text. No other output.
+
+--- PAGE SPECIFICATION ---
+<paste Step 3 verbatim here>
+```
+
+---
+
+## Step 3 -- Page specification (the subagent's design contract)
+
+Hard requirements for the HTML page:
+
+- **Self-contained and theme-aware.** No external fonts/scripts/images/CDNs
+  (CSP blocks them). Honor `prefers-color-scheme` as the default signal AND
+  `:root[data-theme="dark"]` / `:root[data-theme="light"]` overrides.
+- **Header card:** verdict badge (✅ LGTM / ⚠️ LGTM with changes / 🚫 Needs
+  work -- color-coded), PR title linking to `PR_URL`, author, branch → base,
+  head sha (short, `code` style), depth chip, findings count by severity, CI
+  status. When `isDraft`: a DRAFT banner. When the PR title's ⛔ CANNOT MERGE
+  block applies (see output-format.md): an unmissable banner above everything
+  else on the page.
+- **Timeline section (re-review mode):** "Since last review" -- one row per
+  prior finding: ✅ fixed (title struck through) or ⚠️ still open, each with
+  `file:line`. This is the living part of the page. On first review, show
+  "First review of this PR" with the head sha and the review's date filled in
+  from the review file (do not leave the date as a literal placeholder in the
+  output).
+- **Findings**, grouped Critical → Important → Observations → Idiomatic. Each
+  finding is an expandable `<details>` block:
+  - summary row: severity dot + title + `file:line`
+  - body: description, `badCode` in a `<pre>`, `fix` in a `<pre>`, a small
+    hard-rule chip (e.g. "TS-1 · hard rule") when `rule` is set, `agreedBy`
+    chips when 2+ dimensions agreed, `verifierReasoning` as a muted footnote.
+- **Proof block:** when `proof.proven === true`, render a visually distinct
+  "PROVEN -- failing test ran in the worktree" panel: `redOutput` in a
+  `<pre>`, a one-line explanation that the test asserts correct behavior, and
+  `testCode` collapsed behind its own `<details>`. This is the page's
+  centerpiece -- make it prominent (e.g. a red left border) but not garish.
+- **Test Quality + Review Cost sections**, mirrored from the review file,
+  kept concise (verdict + gaps + cost table; no need to reproduce every
+  sentence).
+- **Layout:** every code block (`badCode`, `fix`, `redOutput`, `testCode`)
+  horizontally scrollable within its own container; the page body itself must
+  never scroll horizontally. Keep total page weight sane -- plain `<pre>`
+  with a theme-aware background, no syntax-highlighting library.
+- **No praise language anywhere** (house rule, same as the saved review):
+  state what the code does and the risks it carries, never compliment it.
+
+---
+
+## Step 4 -- Record the URL (fresh post-condition)
+
+When the subagent returns:
+
+**On success (URL returned):**
+1. Append or refresh a `**Artifact:** <url>` line in the saved review file's
+   header block. Idempotent: replace an existing `**Artifact:**` line if
+   present, never duplicate it.
+2. Re-read the review file to confirm the line landed -- this is the receipt
+   (per VERIFICATION.md: a write is not done until re-read from source).
+3. Print one line to the user: `🔗 Living review: <url>`
+
+**On failure (no URL, or the agent errored):**
+- Say so in one line to the user.
+- Do NOT fail or roll back the review over this -- the saved review file is
+  the source of truth; the artifact is an enhancement layered on top of it.
+
+---
+
+## Hard rules
+
+- The renderer subagent runs in the BACKGROUND -- never block printing or
+  delivering the review on its completion.
+- Same PR → same URL, always. Pass `PREV_ARTIFACT_URL` whenever one exists. A
+  fresh URL minted for a PR that already has one is a bug -- treat it as such
+  if you spot it in the receipt.
+- The artifact is private by default; sharing it is the user's decision, not
+  the skill's.
+- Never include secrets or tokens from context. The page contains only what
+  the saved review file already contains -- nothing pulled fresh from
+  scratchpad context that isn't already in the review.
+- Favicon stays `🥩` forever for this artifact -- never change it on
+  republish.

package/packages/software-development/lekker-review/references/context-gathering.md

@@ -0,0 +1,162 @@
+# Context gathering (Step 1)
+
+## Step 1 — Gather Context (run in parallel)
+
+### 1a. PR metadata
+```bash
+gh pr view <PR_NUMBER> --repo <REPO_SLUG> \
+  --json number,title,body,author,headRefName,baseRefName,labels,\
+linkedBranches,mergeStateStatus,additions,deletions,changedFiles,isDraft,headRefOid
+```
+
+**PR-1 title check (run immediately after 1a, before other steps)** — only if
+your `house-rules.md` defines a title/ticket-prefix rule:
+
+```bash
+# Collect ticket IDs from the commit log of this PR
+gh pr view <PR_NUMBER> --repo <REPO_SLUG> --json commits \
+  --jq '[.commits[].messageHeadline | scan("\\[[A-Z]+-[0-9]+\\]")] | unique | join(",")'
+```
+
+1. Check that the PR title matches whatever prefix convention `house-rules.md` defines.
+2. Extract all ticket references from commit messages and merged PR titles in the commit log.
+3. If the PR title is missing the prefix, or is missing any ticket from the commit history:
+   - Record `PR_TITLE_ISSUE = true` and `RECOMMENDED_PREFIX = "<all tickets comma-separated>"`
+   - This will produce an `⛔ CANNOT MERGE` block at the top of the review output (Step 4), before the Summary.
+4. If all tickets are present: `PR_TITLE_ISSUE = false`.
+
+### 1b. Full diff
+```bash
+gh pr diff <PR_NUMBER> --repo <REPO_SLUG> > "$DIFF_FILE"   # fetched ONCE; all agents read this file
+```
+
+### 1c. Issue tracker (optional — skip if you have no ticket-tracker MCP configured)
+Search for tickets referenced in the PR title, body, or branch name using
+whatever issue-tracker MCP tool (Linear, Jira, GitHub Issues, etc.) is
+available in your setup.
+
+Extract: ticket description, acceptance criteria, linked issues, comments.
+Collect ACs as a numbered list — this becomes `AC_LIST` used in Step 3.
+
+If no issue-tracker MCP is configured, skip silently — the review still runs
+fine on the PR body + diff alone.
+
+### 1d. Team chat *(scan: skip, optional)*
+If a chat-search MCP tool (Slack, Discord, etc.) is available, search for the
+PR title keywords / branch name / ticket ID to surface design decisions or
+trade-offs the team discussed outside the ticket. Skip silently if none is
+configured.
+
+### 1e. Docs / wiki *(scan: skip, optional)*
+If a docs-search MCP tool (Notion, Confluence, internal wiki, etc.) is
+available, search for specs, runbooks, ADRs, or design docs related to this
+work. Skip silently if none is configured.
+
+### 1f. Framework/API docs *(scan: skip, optional)*
+If the diff touches a specific framework or third-party API and a docs-search
+MCP for it is available, verify the implementation matches current API
+behaviour and best practices. Skip if not relevant or not configured.
+
+### 1g. Repo placement check — see references/house-rules.md
+Only applicable if your org splits work across sibling repos and you've
+filled in the repo-taxonomy table in `house-rules.md`.
+
+### 1h. Prior review pattern recall *(scan: skip, optional)*
+If you maintain a persistent memory/notes system across review sessions (a
+wiki page, a memory MCP, or even a running Markdown file of "patterns we keep
+seeing in this repo"), pull relevant entries here: known conventions not yet
+in the repo's own CLAUDE.md/README, confirmed false positives from past
+reviews, and recurring bug classes to watch for. Skip entirely if you don't
+have such a system — this step adds value but nothing depends on it.
+
+Do NOT recall or store author-specific patterns ("author X tends to...") —
+scope any such memory to the repo, not the person, so the review stays about
+the code, not the author.
+
+### 1i. Production error monitoring *(scan: skip, optional)*
+If an error-monitoring MCP (Sentry, Rollbar, Bugsnag, etc.) is available,
+search for production errors in the code paths touched by this PR:
+
+```
+query: "<repo-short-name> <key module or filename from diff>"
+query: "<key function/export names introduced or modified in the diff>"
+```
+
+Collect into `MONITORING_SIGNALS`. For each match, note:
+- Issue title and link
+- Event count and affected users in a recent window
+- First seen / last seen — chronic vs. newly introduced
+- Whether the culprit or stack trace references a file in the diff
+
+If `MONITORING_SIGNALS` is non-empty, include a `## 🔥 Production Signals`
+section in the review output (place it immediately after the Summary, before
+findings). Format each entry as:
+```
+- [<title>](<url>) — <N> events / <M> users (recent window) · first seen <date>
+  Files: <relevant files from stack trace>
+  Note: <one sentence — does this PR fix, worsen, or not affect this error?>
+```
+
+If an error traces directly to a function this PR modifies and the PR does
+not fix it, escalate: add a finding under `## ⚠️ Important` noting the
+pre-existing production error in modified code.
+
+If no monitoring MCP is configured or no matches found, skip the section
+silently. Never write "monitoring unavailable" into a review off the back of
+a single failed call; either produce the signals or state the actual reason
+(auth, no project, genuinely zero matches).
+
+An error in the subsystem that corroborates a finding is worth reporting even
+when this PR neither causes nor fixes it — say so explicitly ("not caused or
+worsened by this PR") and tie it to the finding it supports. Check the
+environment tag: a staging-only error is weaker evidence than a production
+one, and claiming otherwise overstates the case.
+
+### 1j. CI check results
+
+```bash
+gh pr checks <PR_NUMBER> --repo <REPO_SLUG> 2>/dev/null
+```
+
+Collect into `CI_STATUS`. Rules:
+- Any **failing** TypeScript/build check → treat as a Critical finding: the
+  branch doesn't compile. Quote the check name and link in the finding.
+- Any **failing** test check → Critical finding: existing tests are broken.
+- Any **failing** lint check → Important finding.
+- All checks passing → note `✅ CI passing` in the review header line.
+- Checks pending → note `⏳ CI pending` in the header.
+- `gh pr checks` unavailable or no checks configured → omit the header note.
+
+### 1k. Existing reviewer comments
+
+```bash
+gh pr reviews <PR_NUMBER> --repo <REPO_SLUG> --json author,state,body 2>/dev/null
+gh api "repos/<REPO_SLUG>/pulls/<PR_NUMBER>/comments" \
+  --jq '.[].body' 2>/dev/null | head -80
+```
+
+Collect into `EXISTING_REVIEWS`. Purpose:
+- **Awareness only** — do NOT anchor your findings on what other reviewers said.
+  If you independently reach the same conclusion, that is fine — but earn it
+  from the diff, not from their comment.
+- **Deduplication** — if an existing review already raised a finding at a
+  specific `file:line`, skip that finding in your output and note
+  `(already raised by <reviewer>)` internally in your deduplication pass.
+- **Design decisions** — if the author replied to a review comment explaining
+  an intentional choice, that context informs whether a pattern is a bug or
+  a deliberate trade-off.
+
+### 1 post-gather — Draft / state check
+
+After Step 1a completes, check the `isDraft` field in the PR metadata.
+
+If `isDraft: true`, prepend this notice to the final review output (before
+the Summary):
+
+> ⚠️ **Draft PR** — this review is on a work-in-progress branch. Some findings
+> may reflect intentionally incomplete work.
+
+Also check `mergeStateStatus`:
+- `BLOCKED` → note in the review header as `🚫 Merge blocked`
+- `BEHIND` → note as `⏰ Branch is behind base`
+- `CLEAN` → no note needed