claude-dev-env 2.3.0 → 2.5.0

package/skills/condensing-instructions/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: condensing-instructions
+description: >-
+  Rewrite existing instruction documents or turn first drafts and requirements
+  into compact, high-information operational instructions without changing or
+  inventing their contract. Use for prompts, skills, policies, runbooks,
+  agent-facing documents, reference instructions, token reduction,
+  deduplication, restructuring, or concise instruction authoring.
+---
+
+# Condensing Instructions
+
+Rewrite an existing instruction document or turn a first draft, notes, or requirements into compact operational instructions. Preserve behavior; reduce length only after the contract is complete and unambiguous.
+
+## Preserve the full contract
+
+Treat every execution-relevant detail as binding: required, prohibited, and permitted behavior; safety and authority boundaries; actors, objects, data or resource kinds, and scope; force, negation, and quantifiers; triggers, defaults, conditions, exceptions, thresholds, and precedence; dependencies, prerequisites, order, timing, duration, persistence, and state; failure and recovery behavior; exact strings, names, paths, URLs, identifiers, commands, flags, numbers, placeholders, schemas, and error text; and input, output, formatting, validation, acceptance, and completion requirements.
+
+Keep rationale or examples only when they define a decision, boundary, exception, exact value, or required behavior. Preserve required frontmatter, tags, wrappers, templates, schemas, and other machine-read structure.
+
+When rewriting, change wording and structure, not behavior. When authoring, supply organization, wording, and conventional editorial choices, but do not invent material obligations, permissions, exceptions, or defaults. Ask one concise blocking question when missing, contradictory, or ambiguous information would materially change behavior, safety, authority, scope, precedence, failure handling, or output. Otherwise proceed.
+
+If no instruction material or requirements are provided, respond exactly: `Provide the instructions or draft requirements.`
+
+## Build a requirement ledger first
+
+Before deleting, merging, or drafting text, record each atomic commitment internally. Capture its force, actor, trigger, action, object or type, required outcome, scope, timing or persistence, dependencies, defaults, exceptions, precedence, failure behavior, and exact literals when applicable.
+
+For an existing document, inventory every behaviorally meaningful statement. Distinguish true duplicates from similar rules that apply to different actors, stages, conditions, or scopes. For a first draft, translate each stated goal into observable behavior or an acceptance condition; mark material gaps instead of silently choosing an answer. Do not promote a preference to a hard rule or average conflicting rules.
+
+Do not expose the ledger unless requested.
+
+## Group rules by the decisions they control
+
+- Group requirements by function or decision point, not by draft order.
+- Default to this sequence when it fits: purpose and scope; inputs and prerequisites; operating defaults; procedures and branches; constraints and safety; outputs and failures; verification. Override it when dependencies require another sequence.
+- Place a safety rule or other constraint before the first action it governs.
+- Within a group, put prerequisites before actions, general rules before narrow exceptions, and production requirements before their checks.
+- Put each exception beside the rule it modifies. State precedence when rules overlap.
+- Give each rule one authoritative location. State a shared actor, condition, default, or scope once at the narrowest level that covers every affected rule.
+- Let a heading carry scope only when every instruction beneath it clearly inherits that scope. Use the fewest headings that preserve navigation.
+
+## Write direct, dense rules
+
+- Use active, imperative language and concrete verbs. Put a condition before its action and an exception immediately after its default.
+- Preserve force and quantifiers. Keep `must`, `never`, `only`, `should`, `may`, `all`, `any`, and exact counts distinct.
+- Combine statements only when their actor, force, scope, trigger, timing, persistence, and exceptions align.
+- Replace true repetition with one rule and a compact list of affected cases. Keep separate statements when repetition protects distinct stages, scopes, or failure modes.
+- Use one sentence per decision. Join clauses only when they form one testable rule.
+- Use paragraphs for cohesive rules and lists for parallel obligations, mappings, or branches. Avoid decorative headings and structural ceremony.
+- Remove non-operative background, history, rationale, transition text, conversational framing, restatement, setup narration, and examples. Remove inventories or folder maps that merely describe the document.
+- Use one term for each concept. Define unfamiliar terms at first use. Do not compress complete sentences into fragments, stacked jargon, or vague shorthand.
+- Preserve operational literals character for character, including spelling, case, punctuation, quoting, and placeholders. Preserve whether a list is exhaustive or illustrative; never replace an exact enumeration with `etc.` or a broader category.
+
+## Imply only what cannot change behavior
+
+Rely on ordinary language competence and document conventions only when every reasonable reader would take the same action. State a detail when omitting it could change permission, safety, actor, object or type, scope, force, trigger, sequence, timing, persistence, precedence, failure behavior, exact output, or acceptance.
+
+Match detail to fragility. Specify exact steps for brittle, high-risk, or order-dependent work. For flexible work, state the required outcome and constraints, then leave the method open.
+
+Never use implication to carry a prohibition, exception, dependency, safety boundary, or exact literal. Do not retain obvious advice that constrains nothing, and do not omit a non-obvious rule because it seems intuitive.
+
+## Pass the quality gate
+
+Run these checks silently:
+
+1. **Coverage:** Map every ledger item to a clause in the finished document.
+2. **Support:** Map every material clause back to a stated or confirmed requirement; remove invented behavior.
+3. **Fidelity:** Compare force, negation, quantifiers, actor, object or type, scope, conditions, exceptions, dependencies, order, timing, persistence, failure behavior, outputs, and protected literals. Nothing may be weakened, broadened, narrowed, contradicted, or altered character for character where exactness matters.
+4. **Boundary behavior:** Test the normal case, each branch and exception, prohibited cases, missing dependencies, failures, and acceptance checks when present. Each case must yield the intended action.
+5. **Clarity:** Resolve ambiguous references, hidden precedence, scattered exceptions, inconsistent terms, and unclear qualifier scope.
+6. **Density:** Delete any sentence that changes no behavior, safety boundary, interpretation, or validation result. Merge remaining text only when the boundary stays equally clear.
+7. **Independent use:** Reconstruct the ledger from only the finished document. It must stand alone without background or unstated context.
+
+Do not finish until every check passes. If multiple versions pass, prefer fewer words, fewer sections, and lower lookup cost. Shorter text never compensates for lost behavior or precision.
+
+## Deliver the requested artifact
+
+Preserve the requested format and required syntactic envelope. If no format is specified, use the leanest clear Markdown structure.
+
+For text supplied in the conversation, output only the finished instruction document. For file tasks, write only the requested paths: edit an existing file in place, and create a new file only when requested. Report changed paths with a concise behavior summary. Do not include the ledger or process narration unless requested.

package/skills/copilot-review/SKILL.md

@@ -1,119 +1,119 @@
----
-name: copilot-review
-description: >-
-  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
-  current PR: each tick it fixes unaddressed findings against HEAD, re-requests
-  review, and exits on convergence. Triggers: '/copilot-review', 'watch
-  copilot', 'babysit copilot review', 'keep re-requesting copilot'.
----
-
-# Copilot Review
-
-Delegates Copilot babysitting to a background subagent so the main session stays free. The subagent loops internally and closes itself on convergence.
-
-## Transport check (before any GitHub step)
-
-Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the subagent prompt so the spawned watcher inherits it.
-
-## When this skill applies
-
-The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to keep re-reviewing after each push, and wants findings auto-addressed between ticks — but does not want the main conversation consumed by polling.
-
-## The Process
-
-### Step 0: Opt-out check
-
-Before any other work, run:
-
-```bash
-python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
-```
-
-Exit 0 — Copilot reviews are disabled: respond with the literal line
-`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
-spawn the subagent, do not call the Copilot reviewer API, do not run any
-other step of this skill. Exit 1 — continue. Gate semantics live in the
-`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
-
-### Step 1: Gather PR context
-
-From the current repo:
-
-```bash
-# MCP: pull_request_read(method="get") returns {number, url, head.sha, base.ref, head.ref, isDraft}
-```
-
-Capture `number`, `head.sha`, owner/repo (from `url`), and branch name. Pass these to the subagent so it does not rediscover them.
-
-### Step 2: Spawn the background subagent
-
-Invoke the `Agent` tool with:
-
-- `subagent_type: "general-purpose"`
-- `run_in_background: true`
-- `description: "Copilot review loop for PR #<N>"`
-- `prompt`: the full instructions in **Step 3 (Subagent prompt template)**, with placeholders filled in from Step 1.
-
-Record the returned agent ID. Report to the user in one or two lines:
-
-- The subagent is running in the background.
-- It self-terminates on convergence.
-- To stop it early, the user says "stop the copilot loop" and you call `TaskStop <agent_id>`.
-- The main session stays free; completion arrives as a notification.
-
-Let the subagent own the cadence. The skill's job in the main session ends once the subagent is spawned and reported.
-
-### Step 3: Subagent prompt template
-
-Pass the prompt in
-[`templates/subagent-prompt.md`](templates/subagent-prompt.md) to the subagent
-word for word, filling in the bracketed values ([NUMBER], [OWNER], [REPO],
-[BRANCH], [HEAD_SHA]) from Step 1. It carries the per-tick work, the escalation
-rule (three consecutive no-review ticks), the fix protocol, the stop conditions,
-and the 20-tick safety cap.
-
-### Step 4: Report back to the user
-
-After spawning, tell the user in one or two lines: subagent ID, PR URL, that it will notify on convergence or blocker. Nothing else.
-
-## Stopping the subagent
-
-- Convergence → subagent stops itself.
-- Blocker → subagent reports and stops.
-- User says stop → `TaskStop <agent_id>`.
-- User asks what loops are running → `TaskList`.
-
-## Ground rules (for the subagent)
-
-- **Append commits.** Each tick adds one new commit on the existing branch with `git commit` and `git push origin [BRANCH]`.
-- **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry. Solve, do not punt.
-- **Respect the PR's current state.** Whatever draft-vs-ready state the PR has when the loop starts is the state the subagent preserves. The user decides when to flip it.
-- **One fix commit per tick.** Batch all of the current tick's findings into a single commit; the next tick handles the next review round.
-- **Use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix for the reviewer ID.** That exact spelling is load-bearing — it is the only form the API accepts.
-
-## Examples
-
-<example>
-User: `/copilot-review`
-Claude: [reads PR context, spawns background subagent with the Step 3 template, reports "subagent X watching PR #123; will notify on convergence"]
-</example>
-
-<example>
-User: "babysit copilot on this PR until it's clean"
-Claude: [same as above]
-</example>
-
-<example>
-Subagent tick fires, latest Copilot review is against an older commit.
-Subagent: [re-requests review, schedules next wakeup, returns]
-</example>
-
-<example>
-Subagent tick fires, Copilot has 2 unaddressed inline findings on HEAD.
-Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, resolves both threads, re-requests review, schedules next wakeup]
-</example>
-
-<example>
-Subagent tick fires, latest review is clean against HEAD.
-Subagent: [reports convergence to parent, terminates — no further wakeups]
-</example>
+---
+name: copilot-review
+description: >-
+  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
+  current PR: each tick it fixes unaddressed findings against HEAD, re-requests
+  review, and exits on convergence. Triggers: '/copilot-review', 'watch
+  copilot', 'babysit copilot review', 'keep re-requesting copilot'.
+---
+
+# Copilot Review
+
+Delegates Copilot babysitting to a background subagent so the main session stays free. The subagent loops internally and closes itself on convergence.
+
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the subagent prompt so the spawned watcher inherits it.
+
+## When this skill applies
+
+The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to keep re-reviewing after each push, and wants findings auto-addressed between ticks — but does not want the main conversation consumed by polling.
+
+## The Process
+
+### Step 0: Opt-out check
+
+Before any other work, run:
+
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
+```
+
+Exit 0 — Copilot reviews are disabled: respond with the literal line
+`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
+spawn the subagent, do not call the Copilot reviewer API, do not run any
+other step of this skill. Exit 1 — continue. Gate semantics live in the
+`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
+
+### Step 1: Gather PR context
+
+From the current repo:
+
+```bash
+# MCP: pull_request_read(method="get") returns {number, url, head.sha, base.ref, head.ref, isDraft}
+```
+
+Capture `number`, `head.sha`, owner/repo (from `url`), and branch name. Pass these to the subagent so it does not rediscover them.
+
+### Step 2: Spawn the background subagent
+
+Invoke the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Copilot review loop for PR #<N>"`
+- `prompt`: the full instructions in **Step 3 (Subagent prompt template)**, with placeholders filled in from Step 1.
+
+Record the returned agent ID. Report to the user in one or two lines:
+
+- The subagent is running in the background.
+- It self-terminates on convergence.
+- To stop it early, the user says "stop the copilot loop" and you call `TaskStop <agent_id>`.
+- The main session stays free; completion arrives as a notification.
+
+Let the subagent own the cadence. The skill's job in the main session ends once the subagent is spawned and reported.
+
+### Step 3: Subagent prompt template
+
+Pass the prompt in
+[`templates/subagent-prompt.md`](templates/subagent-prompt.md) to the subagent
+word for word, filling in the bracketed values ([NUMBER], [OWNER], [REPO],
+[BRANCH], [HEAD_SHA]) from Step 1. It carries the per-tick work, the escalation
+rule (three consecutive no-review ticks), the fix protocol, the stop conditions,
+and the 20-tick safety cap.
+
+### Step 4: Report back to the user
+
+After spawning, tell the user in one or two lines: subagent ID, PR URL, that it will notify on convergence or blocker. Nothing else.
+
+## Stopping the subagent
+
+- Convergence → subagent stops itself.
+- Blocker → subagent reports and stops.
+- User says stop → `TaskStop <agent_id>`.
+- User asks what loops are running → `TaskList`.
+
+## Ground rules (for the subagent)
+
+- **Append commits.** Each tick adds one new commit on the existing branch with `git commit` and `git push origin [BRANCH]`.
+- **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry. Solve, do not punt.
+- **Respect the PR's current state.** Whatever draft-vs-ready state the PR has when the loop starts is the state the subagent preserves. The user decides when to flip it.
+- **One fix commit per tick.** Batch all of the current tick's findings into a single commit; the next tick handles the next review round.
+- **Use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix for the reviewer ID.** That exact spelling is load-bearing — it is the only form the API accepts.
+
+## Examples
+
+<example>
+User: `/copilot-review`
+Claude: [reads PR context, spawns background subagent with the Step 3 template, reports "subagent X watching PR #123; will notify on convergence"]
+</example>
+
+<example>
+User: "babysit copilot on this PR until it's clean"
+Claude: [same as above]
+</example>
+
+<example>
+Subagent tick fires, latest Copilot review is against an older commit.
+Subagent: [re-requests review, schedules next wakeup, returns]
+</example>
+
+<example>
+Subagent tick fires, Copilot has 2 unaddressed inline findings on HEAD.
+Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, resolves both threads, re-requests review, schedules next wakeup]
+</example>
+
+<example>
+Subagent tick fires, latest review is clean against HEAD.
+Subagent: [reports convergence to parent, terminates — no further wakeups]
+</example>

package/skills/e-code-review/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: e-code-review
+description: >-
+  Max-recall code review at a selectable effort level (low, medium, xhigh), with
+  optional auto-fix and an auto-execute loop for any level. Triggers:
+  /e-code-review, /e-code-review low, /e-code-review medium, /e-code-review
+  xhigh, /e-code-review <level> --fix, /e-code-review <level> loop.
+---
+
+# e-code-review
+
+**Pick a level, run that review, optionally fix and loop.** Each level has its own procedure file. Fix application lives in `reference/fix.md`; repeat-until-clean lives in `reference/loop.md`.
+
+## Gotchas
+
+- **`low` stays single-pass.** Do not spawn subagents. One diff read, one findings pass.
+- **`medium` favors precision, `xhigh` favors recall.** At `medium` (8 angles) surface only findings a maintainer would act on. At `xhigh` (10 angles plus a gap sweep) a single non-REFUTED vote carries the finding; do not drop on uncertainty.
+- **`--fix` applies findings once.** Load `reference/fix.md` and follow it — it owns the fix agent, the commit gate, skip logging, and outcome reporting.
+- **`loop` never asks.** After findings, fix nits or stop on bugs. Load `reference/loop.md` and follow it.
+- **`--fix` and `loop` combine.** With both, each loop round runs the level file, then `reference/fix.md`, then re-reviews.
+
+## When this skill applies
+
+Triggers: `/e-code-review <level> [--fix] [loop]`. `<level>` is `low`, `medium`, or `xhigh`. `--fix` and `loop` are each optional and may be used together.
+
+**Refusal — first match wins:**
+
+- **No level, or an unknown level.** Respond exactly: `Which effort level — low, medium, or xhigh?`
+
+## The process
+
+1. Read `<level>` and the optional `--fix` and `loop` flags. Apply the refusal first.
+2. Load `reference/low.md`, `reference/medium.md`, or `reference/xhigh.md`. Run that file as one review cycle, ending in its structured findings report.
+3. If `--fix` is set, load `reference/fix.md` and apply it to that cycle's findings.
+4. If `loop` is set, load `reference/loop.md` and follow it. Each round re-runs the same level file from step 2, plus step 3 when `--fix` is set.
+5. Without `--fix` or `loop`, return the cycle findings and stop.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Route by level; dispatch `--fix` and `loop` |
+| `reference/low.md` | low review procedure — 1 diff pass, no verify |
+| `reference/medium.md` | medium review procedure — 8 angles, 1-vote verify |
+| `reference/xhigh.md` | xhigh review procedure — 10 angles, 1-vote verify, gap sweep |
+| `reference/fix.md` | Fix application, commit gate, skip logging, outcome reporting |
+| `reference/loop.md` | Repeat review/fix rounds until clean |
+
+## Folder map
+
+- `SKILL.md` — route and dispatch.
+- `reference/` — one procedure per level, plus `fix.md` and `loop.md`.

package/skills/e-code-review/reference/fix.md

@@ -0,0 +1,54 @@
+# Fix Behavior (--fix)
+
+When `--fix` is passed, apply the reviewed findings to the working tree.
+
+## Resume the finding agent
+
+For each finding, resume the same Agent-tool agent instance that originally
+surfaced it. That agent applies all relevant fixes, which you provide guidance
+on in your resume prompt.
+
+At `low` — and any time the Agent tool is unavailable — no finder agent exists
+to resume. Apply the fixes yourself, sequentially, in this context, holding to
+every rule below.
+
+## Commit gate
+
+Before returning, the resumed agent attempts a commit on its own change:
+
+1. Run `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py --repo-root <repo
+   root> <changed/added files>` against every file it changed or added.
+2. If the gate reports violations, fix them and re-run the exact same command.
+3. Repeat until the gate returns clean.
+4. Only after a clean gate result does the agent return control and report
+   its outcome.
+
+## Skip candidates
+
+Skip a finding when fixing it would change intended behavior, require changes
+well outside the reviewed diff, or the finding itself is judged a false
+positive.
+
+Every logged skip surfaces exactly once, batched together, in a single 
+consolidated list presented to the user at the very end of the fix pass 
+— after every other finding has been fixed, marked not-needed, or skipped, 
+and never before.
+
+## Reporting outcomes
+
+After fixes land, report the same findings list again through the structured
+findings-report call — the mechanism that renders this review's results as a
+typed list in the host UI — with each finding now carrying an `outcome`:
+`fixed`, `no_change_needed` (the finding was wrong or already handled), or
+`skipped` (real but not applied). Do not repeat the findings as text in the
+response body; the structured call is the record the host UI reads, and the
+batched skip list from above goes in the prose that follows it.
+
+## If findings are fixed later
+
+Whenever a reported finding is fixed later in the session — the user asks for
+the fix, or later work fixes it incidentally — call the structured
+findings-report call again with the same findings, each carrying an
+`outcome` (`fixed`, `no_change_needed`, or `skipped`). Do not repeat the
+findings as text. Make that call immediately after the fixes land, before any
+prose summary.

package/skills/e-code-review/reference/loop.md

@@ -0,0 +1,43 @@
+# Loop until clean
+
+## Act
+
+`loop` on the hub command authorizes the full cycle. After the effort level procedure returns findings, take the matching branch below immediately.
+
+Do not ask whether to fix, which nits to keep, whether to commit or push, or whether to re-review. Do not open a plan fork. Do not end the turn on a recommendation.
+
+Report progress while you work. Stop for the user only on a terminal outcome below.
+
+## Where fixes come from
+
+When `--fix` is also set, each round's fix pass runs `reference\fix.md`
+(relative to this skill's folder) — it owns which agent applies each fix, the
+commit gate, skip logging, and outcome reporting. Apply the branch rules below
+on top of it: they decide whether a round fixes, commits, pushes, and
+re-reviews.
+
+## Scope stays narrow
+
+Auto-fix only verified findings on the review target. Leave deferred PR-body follow-ups and unrelated refactors alone.
+
+## How to class each finding
+
+Use the finding's verified `severity` when the level emits one.
+
+A finding is a `nit` only when that severity is `nit`. Runtime-correctness, security, data-loss, compatibility, and every other non-nit finding is a `bug`.
+
+If the level emits no severity (for example untagged `low` lines), consult your advisor to determine classification.
+
+## Required checks
+
+"Run required checks" means: run `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py --repo-root <repo root> <changed/added files>` against every file changed or added in the round. On any violation, fix it and re-run the exact same command again — repeat until it reports clean.
+
+## Terminal outcomes
+
+Repeat the same-level review/fix cycle until one of these holds:
+
+- **Clean.** Findings are `[]` or `(none)`. Post the proof-of-work PR comment when the target is a PR. Run `gh pr ready` for a draft PR; otherwise state ready.
+- **Nits only.** Every surviving finding is severity `nit`. Fix all of them on the review target. Run required checks. Commit once per loop round. Push. Consider this clean — post the proof-of-work PR comment and mark ready as in the Clean branch above.
+- **Any bug.** Validate each bug-severity finding with an advisor before touching code — confirm it's real and confirm the intended fix. Then fix all validated findings (bugs and nits) on the review target. Run required checks. Commit once per loop round. Push. Run the same effort level on the new head. Repeat until clean, then mark ready as above.
+
+Do not drop findings to force ready. Without `loop`, run one review at the selected level, fix, and return every validated finding.

package/skills/e-code-review/reference/low.md

@@ -0,0 +1,57 @@
+`low effort → 1 diff pass → no verify → ≥min(files,4) findings`
+
+## Turn 1 — read
+
+One tool call: read the unified diff (`git diff @{upstream}...HEAD; git diff HEAD`
+to cover both committed and uncommitted changes, or `git diff main...HEAD` /
+the target passed as an argument). Skip test/fixture
+hunks (`test/`, `spec/`, `__tests__/`, `*_test.*`, `*.test.*`,
+`fixtures/`, `testdata/`) — test-file changes are not reviewed at this level.
+No subagents, no full-file reads.
+
+## Turn 2 — findings
+
+Flag runtime-correctness bugs visible from the hunk alone: inverted/wrong
+condition, off-by-one, null/undefined deref where adjacent lines show the value
+can be absent, removed guard, falsy-zero check, missing `await`,
+wrong-variable copy-paste, error swallowed in a catch that should propagate.
+Also flag — still from the hunk alone — new code that duplicates an existing
+helper visible in the diff context, and dead code the diff leaves behind.
+
+Do **not** flag style, naming, perf, missing tests, or anything outside the
+hunk.
+
+Target **min(files_changed, 4) findings**, most-severe first, reported in one
+call to the structured findings-report call — the mechanism that renders
+findings as a typed list in the host UI — with `{level, findings}`; each
+entry has `file`, `line`, `summary`, `short_summary` (≤60 characters), and
+`failure_scenario`. If you have fewer, do one more pass focused on the largest
+changed file and on any **removed** code blocks. Make that call with an empty
+findings array only if the diff is trivially correct after that pass. Do not
+also print the findings as text.
+
+## Applying fixes (--fix)
+
+The `--fix` flag was passed. Follow `reference\fix.md` (relative to this
+skill's folder) for the exact fix, commit-gate, and skip-handling behavior —
+it governs which agent applies each fix, how a fix gets committed, how a skip
+is logged, and how outcomes get reported. Do not repeat the findings as text;
+follow that document's reporting rules once fixes land.
+
+## If findings are fixed later
+
+Whenever a reported finding is fixed later in this session — the user asks you
+to fix it, or later work fixes it incidentally — follow `reference\fix.md`'s
+reporting rules again: report the same findings through the structured
+findings-report call, each carrying an `outcome`. Do not repeat the findings
+as text. Make that call immediately after the fixes land, before any prose
+summary; the host UI's per-finding status updates only from that call.
+
+## Looping (`loop`)
+
+The `loop` arg was passed. Follow `reference\loop.md` (relative to this
+skill's folder) for how to re-run Turn 1 (read), Turn 2 (findings), and (if
+`--fix` is also present) `reference\fix.md`'s fix pass, repeatedly —
+including its exit condition, iteration cap, and re-invocation rules. Do not
+treat a single pass through this document as complete while `loop` is active;
+hand control to that document instead of stopping at Turn 2.