Super Review

Super Review

Version: 1.6.1

Compatibility: Requires filesystem access to the target repository or directory and permission to create or update its root FINDINGS.md. Git and code-search tools are recommended. Python 3 is recommended for the bundled fingerprint, report-validation, safe-write, and test scripts.

Invocation gate

Run only after an explicit skill mention. For direct installs, prefer $super-review in Codex, accept @super-review on mention-based clients, and accept /super-review where supported. For marketplace installs, also accept $super-review:super-review in Codex and /super-review:super-review in Claude Code. Cursor installs the same skill through the repo-root Cursor plugin; invoke it explicitly by the skill/command name after install. Do not activate for a generic review, audit, architecture assessment, security review, or codebase analysis.

$super-review [repository path or directory] [optional review mode and context]
@super-review [repository path or directory] [optional review mode and context]
/super-review [repository path or directory] [optional review mode and context]
$super-review:super-review [repository path or directory] [optional review mode and context]
/super-review:super-review [repository path or directory] [optional review mode and context]

Use the supplied target. If none is supplied, use the current repository or workspace. Resolve the canonical root to an absolute, symlink-resolved path from the version-control root when available; otherwise use the absolute, symlink-resolved supplied directory root.

Trusted skill root

Resolve SKILL_ROOT once as the canonical absolute parent directory of this loaded SKILL.md. Resolve every bundled reference and helper from SKILL_ROOT; never from the current working directory, target repository, or a target-relative scripts/ path. Before executing a helper, verify that the resolved path remains inside SKILL_ROOT/scripts and is a regular non-symlink file from the loaded skill package.

Invoke bundled Python helpers in isolated mode:

python3 -I "$SKILL_ROOT/scripts/<helper>.py" ...

Use the platform-equivalent isolated Python invocation when python3 -I is unavailable. Do not substitute a same-named repository script.

Non-negotiable output invariant

Every valid invocation must create or refresh exactly:

<canonical-root>/FINDINGS.md

In REVIEW ONLY, that file is the sole permitted repository modification. Never write a competing report in a nested package or under another name. Before reading, revalidating, or replacing it, load and follow the canonical findings lifecycle. A run is incomplete until the current report is validated and safely written, or a concurrent-edit conflict is reported without overwriting another writer.

Progressive loading contract

Do not preload the protocol. At activation, load only:

1. Core mandate, context, review modes, and objectives.
2. Evidence and review principles.
3. Canonical FINDINGS.md lifecycle.
4. Phase applicability and deep-loading rules.

Before any repository-defined command, load the untrusted-repository command-safety gate.

Consider phases 0 through 22 in order and apply the applicability guide before deep loading. Load one applicable phase file immediately before performing that phase. Close a conditional phase without its deep reference only after bounded searches establish that no relevant first-party code or behavior exists. Record Not applicable: <specific evidence basis> and reopen the phase if later evidence changes applicability.

For phase 20, load only the directly linked stack references supported by repository evidence: JavaScript and TypeScript, Python, Go, Rust, Java and Kotlin, C# and .NET, C and C++, SQL and query systems, and mobile clients.

Before canonicalizing records, load identity and cross-reference rules, then only the templates needed for actual records: defects and risks, improvements and alternatives, feature decisions, and positive patterns. Before report assembly, load the final report schema. Before completion, load the quality bar and final gates.

All referenced rules are normative. Progressive loading changes when instructions enter context, not whether applicable checks are performed.

Execution architecture

1. Resolve instructions, authorization, mode, target, root, exclusions, compatibility contracts, and supplied context.
2. Snapshot repository state and the exact FINDINGS.md bytes/digest. Preserve protected human blocks and build the prior-report revalidation ledger.
3. Establish command safety before executable validation.
4. Perform phases 0 through 22 in order while maintaining coverage and evidence ledgers.
5. Checkpoint long-running analysis outside the repository, bound to root, revision, worktree state, and starting report digest; invalidate stale phase results after changes.
6. Revalidate every prior claim, then perform independent current-repository discovery. The old report never limits coverage.
7. Canonicalize by root cause or decision basis; compute deterministic fingerprints; preserve active and retired IDs; derive summaries and roadmap from canonical records.
8. Generate the candidate outside the repository. Run python3 -I "$SKILL_ROOT/scripts/validate_findings.py" <candidate-path> and fix every error.
9. Reread the current report immediately before replacement (python3 -I "$SKILL_ROOT/scripts/validate_findings.py" --snapshot --metadata-only --json <canonical-root>/FINDINGS.md; add --out <file-outside-repo> instead of --metadata-only when the exact bytes are needed for annotation merging). Use python3 -I "$SKILL_ROOT/scripts/commit_findings.py" ... or a demonstrably equivalent exact-byte, digest-gated, annotation-preserving atomic write that also refuses a candidate whose stated canonical root belongs to a different repository. On conflict, reread, revalidate, merge, regenerate, and retry; never force an overwrite.
10. Reread the committed file, rerun the absolute-path validator with --canonical-root <canonical-root> via the skill-root CLI, and verify the stated canonical root, revision, completion status, IDs, summaries, roadmap, validation record, annotations, and ending.

Review modes and evidence

Use the requested mode; default to REVIEW ONLY. The root FINDINGS.md update applies in every mode. Never infer permission for source changes, dependency installation, network or secret access, production systems, migrations, public-contract changes, feature removal, deployment, publication, commits, pushes, or irreversible actions.

Confirmed and high-confidence records require current repository evidence. Distinguish facts, supported inferences, hypotheses, and unavailable evidence. Trace important behavior through callers, consumers, tests, schemas, configuration, persistence, deployment, failures, retries, cleanup, compensation, and compatibility paths. Manually verify scanner output and protect secrets and personal data.

Exhaustiveness means considering every meaningful first-party area and required review dimension. It does not mean inventing findings. For unsupported or inapplicable fields, alternatives, categories, or subsystem analyses, write Not applicable: <specific evidence-based reason> or Not established: <missing evidence>.

Completion response

After safe write and revalidation, report only:

• Exact FINDINGS.md path.
• Reviewed branch, revision, or directory state.
• Whether the prior report was fully revalidated.
• Highest-priority active canonical IDs, or that none were confirmed.
• Validation status and material limitations.

Do not duplicate the full report in chat unless explicitly requested.