argus-review

name	argus-review
description	Use when reviewing a pull request, branch, or local diff and the reader needs an evidence-backed, plain-language HTML guide to the change. Apply for self-review, reviewing another author's change, large cross-system diffs, or when a dependency-ordered file-and-unit review is needed.

Argus Review

Build a guided review, not a list of generic warnings. The output helps a reader understand the changed system before inspecting code.

Required skills

• REQUIRED SUB-SKILL: Use crew to create durable review records and plan review scale. An Argus invocation authorizes this use. The Crew planner may assign one reviewer or a parallel review run.
• REQUIRED SUB-SKILL: Use flow to render the PR-level reading journey.
• REQUIRED SUB-SKILL: Use explain-it to render linked file pages and code-on-demand unit views.

Intake and isolated source

1. Accept a PR URL or number, or a local branch and repository.
2. Create a run folder at ~/artifacts/argus-review/<date>-<repository>-<target>/ with htmlfiles/, review-model.json, README.md, contract.md, progress.md, and log.md.
3. For a PR, use gh to resolve its repository, target ref, and default base, then create a fresh temporary checkout outside the source repository. For a local branch, use its repository only as a source and create a separate temporary checkout. Do not modify the user’s checkout.
4. Always compare the target with the latest remote base. If the target does not contain it, stop before review and ask whether to review as-is. If the user updates the branch, fetch again and repeat the comparison. Never merge or rebase automatically.
5. Register cleanup before work starts. Remove the temporary checkout after success, failure, cancellation, or interruption. Keep only the artifact, review model, and revision identifiers.

Planner contract

The planner reads the diff and surrounding code, then records: change size, changed-file coverage, subsystem buckets, dependencies, reading order, review scale, and safe validation commands.

Use one reviewer for a small, contained change. Use Crew for a large or cross-system change: a planner maps coverage, reviewers examine distinct buckets, and a final lead verifies and consolidates results. Record why that choice was made.

Order readers by understanding, not file name:

1. Foundations: schemas, contracts, shared types, configuration, manifests
2. Backend and integrations
3. Frontend consumers
4. Tests
5. Supporting files: lockfiles, generated output, documentation, and ignore rules

Dependencies override this order. Group files into meaningful domain buckets, then link later files to the prerequisite file or unit.

Review model

Assign stable IDs and links to every PR, bucket, file, and unit.

• PR: intent, cautions, and reading journey.
• Bucket: purpose, dependencies, and files.
• File: existing role, overall change, and reason for change.
• Unit: a function, class, component, schema, imports, constants, or cohesive section. Do not use raw diff hunks as the unit when a clearer code boundary exists.

Every unit states what changed and why it matters. Add a reviewer note only when it is a real finding or a human judgement that cannot be safely or cheaply verified.

Verify before warning

Check objective claims in the temporary checkout before reporting them: resolve imports and symbols, inspect callers and types, run focused lint, type, or test commands when the planner marks them safe. Omit routine successful checks.

Report a verified failure with location, plain-language impact, and evidence. If a check was not run because it is unsafe, expensive, or needs product judgement, state the exact human decision instead of a vague caution.

Render and deliver

Use Flow for the index page that explains the PR intent, cautions, buckets, and recommended reading order. Use Explain It for linked file pages in the same site. For Argus, the plain-language-first requirement overrides Explain It's visible-diff default: reveal code, commands, and technical evidence only through explicit Inspect controls.

Keep tests concise and Supporting files grouped in one compact section. Link all references directly to the cited file or unit. Verify every cross-page and in-page link, then visually inspect and open htmlfiles/index.html.

Do not

• Post GitHub comments in this version.
• Leave a clone, dependencies, or generated repository data after completion.
• Present a check as a reviewer task when Argus can verify it itself.
• Turn a failed check or missing evidence into “no findings.”