git:20260908.131d2e1 to git:20260916.c7c4903

21 added, 20 removed. Audit A to A.

---

name: repository-review

- description: Audit a whole repository across architecture, source, tests, tooling, security, CI/CD, docs, and releases with ranked findings. Use for cross-cutting audits, not one diff.

+ description: Review a diff, patch, branch, pull request, or whole repository for correctness, regression, and security defects. Use for code reviews and repository audits.

license: MIT

metadata:

author: Médéric HURIER (Fmind)

source: github.com/fmind/dot/tree/main/skills/repository-review

created: "2026-08-01"

- updated: "2026-09-07"

+ updated: "2026-09-15"

---

# Repository Review

- Audit the whole delivery system read-only and report ranked, evidence-backed findings; [diff-review](../diff-review/SKILL.md) owns one change, [github-issues](../github-issues/SKILL.md) turns findings into issue drafts, and [project-health](../project-health/SKILL.md) applies the fixes.

+ Review code or a repository read-only and report actionable defects. Select the requested scope before loading a procedure; a patch review does not imply a whole-repository audit. [plan-review](../plan-review/SKILL.md) owns proposals; [project-health](../project-health/SKILL.md) owns applying broad fixes.

## Workflow

- 1. **Scope the review**: Read the repository instructions and the stack, CI, security, or documentation skills the requested dimensions need; confirm which live systems are authorized and treat every other credential, cluster, project, deployment, or release as unavailable.

- 1. **Record the candidate**: Capture branch, `HEAD`, upstream, and `git status --short`; distinguish staged, unstaged, and untracked paths, treat pre-existing changes as user-owned, and state whether evidence concerns committed `HEAD`, the dirty tree, or both.

- 1. **Map the system**: Inspect manifests, entry points, package boundaries, tasks, hooks, workflows, deployment and release automation, docs, generated files, and runtime configuration against the [review matrix](references/review-matrix.md).

- 1. **Run native checks**: Iterate with `mise run check`, targeted `check:*` subtasks, and `mise run test`; invoke [secure](../secure/SKILL.md) only when the request needs the full security boundary.

- 1. **Gate the candidate**: Run the full gate (`mise run all`); if the tree carries unrelated changes and the gate write-formats, run it in an isolated working-tree copy containing the candidate edits or fall back to `mise run check` and `mise run test` (see [mise](../mise/SKILL.md)).

- 1. **Inspect live evidence read-only**: Compare the exact `HEAD` SHA with CI checks, deployments, tags, releases, or runtime observations only where authorized and reachable; a green result for another head is stale.

- 1. **Challenge each conclusion**: Reproduce high-impact claims when safe, prefer repository or dependency source over assumptions, and separate an observed defect from a speculative risk.

- 1. **Report findings**: Lead with **Key findings** ranked `P0`–`P3` (scale in [diff-review](../diff-review/SKILL.md)), each with the defect, impact, and direct file, command, CI, or runtime evidence; if none are material, say so and list residual gaps.

- 1. **State proof and actions**: Report the highest proven rung of the [proof ladder](../production-readiness/SKILL.md) with each check marked pass, fail, blocked, or not run, then list **Actions** by priority, each starting with a verb and naming the owner or required authority.

+ 1. **Select scope**: for a diff, patch, branch, PR, or self-review, follow [diff review](references/diff-review.md). For an entire repository or cross-cutting audit, follow [repository audit](references/repository-audit.md) and the [review matrix](references/review-matrix.md). Load only the requested mode.

+ 1. **Record the candidate**: read repository instructions and inspect Git status; distinguish the base/head, staged, unstaged, and untracked changes relevant to the review. Preserve user work and tie evidence to that candidate.

+ 1. **Establish intent**: trace requirements through the affected source, callers, tests, and contracts; inspect generator inputs for generated or vendored changes. Challenge speculative abstractions and tests that bypass the public boundary only when they cause a concrete defect.

+ 1. **Trace risk**: examine reachable failures in correctness, permissions, data integrity, concurrency, compatibility, and resource lifecycle within scope. Use [secure](../secure/SKILL.md) for security-sensitive changes such as authorization, uploads, deserialization, subprocesses, credentials, and agent tools. Trace removed safeguards through callers and history, and search for variants of confirmed defects.

+ 1. **Verify proportionately**: establish findings with source evidence, focused tests, or safe experiments. A read-only review does not automatically require tests or a build. Reuse passing results while relevant inputs remain unchanged; run a full gate only for explicit qualification, repository requirements, or cross-cutting risk. Isolate write-formatting checks when unrelated work is present.

+ 1. **Report findings**: rank actionable defects using the scale below. Give the exact location, reachable trigger, evidence, impact, and smallest correction. Discard preferences and speculation; if none are material, say so. Summarize candidate identity, checks actually run, and remaining limits without expanding validation just to fill a report.

- ## Gotchas

+ ## Severity

- - **Review only**: A review request includes inspection, bounded validation, and a useful local report or issue draft. Applying fixes, creating remote issues/comments, deploying, or publishing follows the user's authorized scope.

- - **Dirty tree**: Preserve it and state which candidate each check covered; a full gate on a dirty tree is coherent only against a materialized candidate.

- - **Partial scan**: Keep the exact timeout, unavailable database, skipped target, or truncated scope; a partial scan is neither green nor finding-free.

- - **Stale CI**: Report the checked SHA and the reviewed SHA; never transfer a result across commits.

- - **Documentation drift**: Prove mismatches against live tasks, CLI metadata, files, workflows, or generated output, not prose alone.

- - **Unavailable runtime**: Name the missing tool, credential, service, cluster, or authorization and stop at the local boundary; readiness is not runtime acceptance.

+ - **P0**: immediate security breach, irreversible data loss, or broad outage risk.

+ - **P1**: likely correctness, security, or availability defect that should block merge.

+ - **P2**: material edge-case, maintainability, performance, or test defect worth fixing before or soon after merge.

+ - **P3**: minor issue, reported only when the user asked for an exhaustive review.

+ ## Boundaries

+ - **Review only**: inspection, bounded validation, and local reports are in scope. Editing code, resolving threads, approving PRs, creating remote issues/comments, deploying, or publishing requires the corresponding authorization.

+ - **Evidence limits**: distinguish observed defects from risks. Keep scan timeouts, skipped targets, unavailable dependencies, and other material gaps explicit; partial evidence is not full qualification.

+ - **Live evidence**: inspect only authorized targets. Compare CI, tags, releases, or runtime observations with the exact reviewed revision; never transfer a green result across commits or equate local checks with deployed acceptance.

## Documentation

- - Companion skills: [diff-review](../diff-review/SKILL.md) (one change and the `P0`–`P3` scale), [production-readiness](../production-readiness/SKILL.md) (proof ladder and go/no-go), [secure](../secure/SKILL.md) (security boundary), [github-issues](../github-issues/SKILL.md) (findings to issue drafts), [project-health](../project-health/SKILL.md) (apply the fixes).

+ - Companion skills: [github-pull-request](../github-pull-request/SKILL.md) (acting on review threads), [github-issues](../github-issues/SKILL.md) (findings to issue drafts), [quality-assurance](../quality-assurance/SKILL.md) (test campaigns), [production-readiness](../production-readiness/SKILL.md) (proof ladder and go/no-go), [mise](../mise/SKILL.md) (validation tasks).