agentleFS
jnsfhrmnnjnsfhrmnn/jf-agentic-coding-starter-kit/.claude/skills/review-loop/SKILL.md

review-loop

Skill1 starsChanged 4 months agoMITView on GitHub

Deep, iterative, evidence-based review of existing repository artifacts such as code, architecture, plans, specifications, prompts, skills, rules, configuration, documentation, tests, and release output. Use when asked to review, audit, harden, verify, or refine completed work; after productive changes covered by .claude/rules/loop-policy.md; or when reviewing the current session delta, an explicit target, or all session work. Produces an authority-aware local disposition for every real finding: persist it only when repository writes are authorized, otherwise name its exact proposed SSOT or task target as PENDING-AUTH.

59 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use motion-design, polish and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • soilmassSkill

    motion-design

    Create animations and motion graphics using industry standards. Use when asked to animate UI elements, create video content, implement transitions, or build motion systems. Implements W3C Design Tokens, Material Design 3 baseline, and Lottie specification compliance.

    Also in 5 projects that use this

  • HK-hubSkill

    polish

    Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.

    Also in 3 projects that use this

  • GoogleSkill

    to-spec

    Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.

    Also in 4 projects that use this

  • GoogleSkill

    improve-codebase-architecture

    Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

    Also in 5 projects that use this

  • AWSSkill

    ship

    Finalize dev work on an issue branch — update docs, push, and open a PR.

    Also in 4 projects that use this

  • MicrosoftSkill

    council

    Convene the persona panel — six orthogonal review lenses — on a target. Cold independent fan-out, debate-to-consensus, synthesized verdict with recorded dissent and a roster manifest.

    Also in 3 projects that use this

  • +4 more from google

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. 0 are common, 16 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 52 edited versions we read keep these.

  • 16

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Audit-only: default when the user asks to review, diagnose, inspect, or report.

    line 16
  2. Very specific:

    Review + fix: use when the user explicitly requests fixes, uses --fix, or the review is a verification phase inside an already-authorized …

    line 18
  3. Distinctive:

    Non-mutable target: always audit-only.

    line 21
  4. Distinctive:

    Never commit, publish, deploy, contact another repository, or broaden scope unless the current request separately authorizes it.

    line 23
  5. Distinctive:

    Always check these core dimensions:

    line 48
  6. Distinctive:

    Add the applicable type lens:

    line 59
  7. Distinctive:

    Read repository instructions and architecture before selecting commands.

    line 78
  8. Distinctive:

    Use deterministic checks for mechanical facts and LLM judgment for semantic intent, coherence, omissions, and trade-offs.

    line 79
  9. Distinctive:

    Never expose secrets, credentials, private data, or raw sensitive output.

    line 88
  10. Distinctive:

    Do not silently filter uncertain high-impact suspicions.

    line 105
  11. Very specific:

    Read AGENTS.md, CLAUDE.md, applicable skills/rules, and tasks/INDEX.md.

    line 113
  12. Distinctive:

    REFINE: only in authorized Review + fix mode.

    line 125
  13. Distinctive:

    CONVERGENCE: stop when no critical/high finding remains and another pass finds no substantial new issue.

    line 128
  14. Distinctive:

    Check the in-scope set for contradictions, missing connections, ripple effects, interface drift, duplicated SSOT state, and whether the …

    line 139
  15. Distinctive:

    Before fixing a critical/high finding below 90 confidence, ask an independent agent to try to disprove it when one is available.

    line 146
  16. Very specific:

    Use --panel by assigning distinct dimensions to independent agents, then deduplicate their evidence.

    line 152
  17. Distinctive:

    Use the narrowest existing SSOT.

    line 177
  18. Distinctive:

    If the invariant does not balance, the review is not complete.

    line 192
  19. Distinctive:

    every local disposition and the balanced completion invariant.

    line 202

“Common” is measured: kept by at least 6 in 10 of the 52 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Review Loop

Review existing work adversarially until coverage and evidence converge. The goal is to find real weaknesses, not to generate a long list or defend earlier work.

Determine Authority And Mode

Respect the authority of the current user request:

  • Audit-only: default when the user asks to review, diagnose, inspect, or report. Read and verify, but do not mutate the reviewed artifacts.
  • Review + fix: use when the user explicitly requests fixes, uses --fix, or the review is a verification phase inside an already-authorized build/change task. Keep fixes inside that authorized scope.
  • Non-mutable target: always audit-only.

Never commit, publish, deploy, contact another repository, or broaden scope unless the current request separately authorizes it.

Resolve Scope

Choose one scope before reviewing:

  1. An explicit path, module, diff, PR, or named artifact overrides all defaults.
  2. With no target, review the current session delta: every artifact created or changed since the last completed review-loop pass. Include staged, unstaged, untracked, and committed session work plus non-code artifacts.
  3. --all reviews all work produced in the session, even if reviewed earlier.
  4. --deep increases depth, not scope.
  5. --panel requests independent reviewers for distinct dimensions.

List the concrete inventory before classification. Do not sample silently. If earlier review coverage cannot be reconstructed after context compaction, state the uncertainty and use an explicit target or conservative full coverage.

For more than roughly eight materially different artifacts, present a compact coverage proposal and ask only if choosing full review versus risk-focused triage would materially change time or outcome.

Classify The Artifacts

Always check these core dimensions:

  • correctness and consistency with requirements and SSOTs;
  • completeness and missing paths;
  • robustness, edge cases, and failure recovery;
  • security, privacy, abuse, secrets, and data locality;
  • performance, scalability, and resource use where relevant;
  • interface, schema, and compatibility risk;
  • maintainability, drift, and regression risk;
  • evidence quality.

Add the applicable type lens:

TypeAdditional focusPreferred evidence
Code/architectureboundaries, concurrency, complexity, error handling, testsproject-native test/lint/typecheck/build/diff
Gate/guardfail-closed behavior, bypasses, false positives/negativespositive and negative trigger cases
Plan/spec/designgoals, acceptance criteria, assumptions, feasibility, alternativesrequirements and SSOT comparison
Config/infra/schemasafe defaults, validation, idempotence, migration/rollback, secretsparser, validator, lint, dry run
Prompt/skill/ruletrigger precision, ambiguity, precedence, scope, counterexamplesvalidator plus realistic trigger/non-trigger cases
Documentationaccuracy against repository reality, paths, commands, linkspath/link/command checks
Data/contentprovenance, semantic consistency, completeness, sensitive datasource comparison plus LLM semantic review
Process/workflowhappy path, failures, ownership, restartability, lost-task riskwalkthrough and failure simulation

Apply multiple lenses when an artifact has multiple roles. For an unknown type, derive and state the most relevant quality and failure dimensions from first principles.

Use Evidence Safely

  • Read repository instructions and architecture before selecting commands.
  • Use deterministic checks for mechanical facts and LLM judgment for semantic intent, coherence, omissions, and trade-offs.
  • Show actual sanitized evidence: exit code, test result, diff, path/line, or fact checked against its source.
  • Label anything that cannot be verified as unverified; never report false green.
  • Inspect unfamiliar scripts and dependency hooks before executing them.
  • Reuse existing processes where possible. Stop any temporary server, watcher, or process started solely for verification.
  • Never expose secrets, credentials, private data, or raw sensitive output.

For code, explicitly consider injection, authorization, input validation, output encoding, path traversal, unsafe subprocesses, secrets, cryptography, deserialization, uploads, SSRF, concurrency, dependency risk, insecure defaults, and fail-open error handling when applicable.

Finding Model

Every finding records:

ID | artifact/location | dimension | severity | confidence | problem | evidence | recommendation | status

Severity is critical, high, medium, or low. Confidence is 0–100 and measures whether the diagnosis is correct, not its impact. Prioritize by both. Do not silently filter uncertain high-impact suspicions; verify them before a fix. Do not inflate style preferences or pre-existing unrelated issues into findings.

Run The Review

Phase A: Scope And Baseline

  • Read AGENTS.md, CLAUDE.md, applicable skills/rules, and tasks/INDEX.md.
  • Inventory and classify every artifact in scope.
  • Record Git/status baseline without modifying or hiding user changes.
  • Select the project-native evidence for each artifact.

Phase B: Review Each Artifact

For each artifact, up to 12 iterations but stopping early on convergence:

  1. STAND: identify artifact, type, and intended contract.
  2. CRITIQUE: apply core dimensions, type lenses, edge cases, and evidence.
  3. DECIDE: select verified findings in severity/confidence order.
  4. REFINE: only in authorized Review + fix mode; use the smallest coherent change and preserve unrelated work.
  5. VERIFY: rerun the relevant checks and inspect the actual diff.
  6. CONVERGENCE: stop when no critical/high finding remains and another pass finds no substantial new issue.

Log compactly:

Artifact <path>, iteration N — findings: C/H/M/L | fixed: <IDs> | open: <IDs> | evidence: <result>

Phase C: Cross-Artifact Pass

Check the in-scope set for contradictions, missing connections, ripple effects, interface drift, duplicated SSOT state, and whether the combined result solves the stated problem. This pass remains limited to artifacts and state inside the current repository.

Independent Verification

Before fixing a critical/high finding below 90 confidence, ask an independent agent to try to disprove it when one is available. Give it the artifact, claimed defect, applicable contract, and verification tooling, but not the desired conclusion. If no agent is available, perform and log a contrary refutation pass in the current context.

Use --panel by assigning distinct dimensions to independent agents, then deduplicate their evidence. For a reproducible finding at confidence 90 or above, a logged cause/fix confirmation may replace fan-out.

Phase D: Local Finding Disposition

Give every real finding exactly one terminal disposition. Persist findings only when the current request already authorizes repository writes. In audit-only mode without that authority, do not mutate a source of truth merely to satisfy this phase; prepare the exact proposed target and use PENDING-AUTH.

  • FIX-DONE: fixed in authorized scope and verified.
  • OWNER-SSOT: recorded in the relevant feature spec, master feature, architecture record, QA evidence, or release record.
  • TASK-INDEX: continuation recorded once in tasks/INDEX.md through /csk-start, linked to its owner, only when it remains open/blocked, will span the current session, is explicitly deferred, or is a verified interruption point. Do not create and close a row for same-turn review/fix work.
  • ASK: a material user decision is still required; persist a blocked task only when that decision must survive beyond the current session and repository writes are authorized.
  • PENDING-AUTH: audit-only finding with an exact proposed local SSOT/task target, awaiting permission to persist it.
  • DROP: false positive, accepted risk, or explicitly rejected item with reason.

Use the narrowest existing SSOT. Do not duplicate feature status in the task index. With write authority, keep the complete review record and every continuation inside the current repository. Without it, name that exact local target without writing.

The completion invariant is:

all findings == FIX-DONE + OWNER-SSOT + TASK-INDEX + ASK + PENDING-AUTH + DROP
undisposed findings == 0

An ASK is durably complete only after its blocked continuation is stored locally. PENDING-AUTH makes the read-only report complete but not durably conserved; state that limitation and request one consolidated authorization. If the invariant does not balance, the review is not complete.

Final Handoff

Report:

  1. scope and coverage;
  2. findings ordered by severity and confidence;
  3. fixes and actual verification evidence, if authorized;
  4. cross-artifact risks;
  5. every local disposition and the balanced completion invariant;
  6. anything unverified or deliberately not reviewed.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.