LLM Skill Review

Mechanical routing: don't decide from memory or from the "Wrong skill?" prose below -- run tools/review.sh route <path> [<path> ...] first (paths of the files you're about to review). It wraps tools/which-gate.sh and prints the correct skill + sentinel + runner for each artifact. If the router says a different skill, follow the router, not this banner. If the router errors or is unavailable, stop and report -- do not fall back to the prose. The banner is an inner backstop, not a substitute for the mechanical check.

Purpose: The primary, default reviewer for ANY skill.md file or skill-adjacent tooling -- covers both LLM-execution safety and prose/design quality in one pass, so a skill review no longer needs a separate progressive-harsh-review pass to also judge whether it is a well-written, sensible artifact for a human.

Wrong skill? Use progressive-harsh-review instead only for non-skill artifacts -- plans, specs, designs, general documents. Conventional code PR review -> code-review-battery (skill/tooling-infrastructure changes should still redirect here first). Quick code comments -> providing-code-review.

Announce at start: "I'm using the llm-skill-review skill to review this as LLM-execution infrastructure, not ordinary app code."

Companion Skills

• progressive-harsh-review: Reviews non-skill deliverables (plans, specs, designs, documents) with the same adversarial rigor; this skill absorbed its skill-review responsibility (see Prose/Design Quality Axes below)
• code-review-battery: Conventional code PR review; escalate here for ordinary application-code changes bundled alongside skill/tooling changes. Also runs alongside this skill (not instead of) for skill-adjacent shell scripts specifically -- see the When to Use exception below
• skill-health-check: Structural lint (frontmatter validity, line budget) -- run before this skill, not instead of it; use think-twice (fresh-perspective sub-agent) if this review gets stuck in a circular loop
• superpowers-doctor: Runtime/ecosystem diagnostics (trigger collisions, orphaned installs) after this skill's review passes

Reference index

Load reference.md selectively - do not load it in full unless you need multiple sections.

Load a section with this block. Replace <section heading> with the exact string from the table above. It resolves an installed copy first, falls back to a source checkout, and exits non-zero with a named reason rather than proceeding on missing content.

_ks_ref=""
_ks_loader=""
for _candidate in \
  "$HOME/.claude/skills/sp-llm-review/reference.md" \
  "$HOME/.codex/skills/sp-llm-review/reference.md" \
  "$HOME/.agents/skills/sp-llm-review/reference.md"
do
  if [ -r "$_candidate" ]; then _ks_ref="$_candidate"; break; fi
done
if [ -n "$_ks_ref" ]; then
  _ks_loader="$HOME/.codex/superpowers-plus/tools/section-loader.sh"
else
  _project_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
  _source_dir="$_project_root/skills/engineering/llm-skill-review"
  if [ -n "$_project_root" ] && [ -r "$_source_dir/skill.md" ] && \
     [ -r "$_source_dir/reference.md" ] && \
     [ -r "$_project_root/tools/section-loader.sh" ]; then
    _ks_ref="$_source_dir/reference.md"
    _ks_loader="$_project_root/tools/section-loader.sh"
  fi
fi
[ -r "$_ks_ref" ] || { printf 'reference missing\n' >&2; exit 1; }
[ -r "$_ks_loader" ] || { printf 'section-loader missing\n' >&2; exit 1; }
# Replace <section heading> below with one of the exact strings from
# the Reference index table above before running.
_section='<section heading>'
bash "$_ks_loader" "$_ks_ref" "$_section" \
  || { printf 'section not found: %s\n' "$_section" >&2; exit 1; }

When to Use

This is the default reviewer for skill.md files and skill-adjacent tooling -- invoke it instead of progressive-harsh-review or code-review-battery for these, not alongside them as a third opinion. Exception: for skill-adjacent shell scripts and tool wrappers specifically, also run code-review-battery -- its ShellRuntimeAuditor persona activates unconditionally on shell content regardless of path, because this skill's own pre-push gate (tools/pre-push-llm-skill-review-gate.sh) only mechanically requires its sentinel for skills/**/*.md changes, not standalone .sh/.js/.py/.mjs files -- run both for a change that touches both content types. This is the one carve-out to the "instead of, not alongside" rule above.

Invoke automatically when changes touch any of these areas:

• skills/**, tools/**, scripts/**, setup/**, mcp/**
• install.sh, install-*.sh, uninstall.sh
• .ai-guidance/** (AGENTS.md overflow -- same audience, just split out on a line-count limit)
• AGENTS.md, CLAUDE.md, CODEX.md, COPILOT.md, GEMINI.md, AGENT.md, at any path depth (see tools/md-files-changed.sh's LLM_OWNED_REGEX for the single source of truth on this boundary)
• plugin manifests, routing files, hook specs, or agent-specific configuration

Also invoke when the user asks for: harsh review of skills, prompts, shell tooling, installers, or agent infrastructure; review for Claude Code/Augment Code/Cursor compatibility; review for prompt/runtime determinism; review of MCP or tool-calling behavior; review before pushing skill changes.

Do NOT use as the primary skill for: pure product UX review; ordinary application code with no skill/tooling/runtime implications; early brainstorming before artifacts exist; non-skill plans/specs/designs/documents (use progressive-harsh-review).

Review Doctrine and Heuristics

Reviews for failure modes frontier models actually exhibit. Default stance: REJECT unless clearly proven otherwise. Full doctrine and heuristics list: load reference.md on demand (section: Review Doctrine and Heuristics).

Primary Review Axes

Score each axis from 0.0 to 10.0 and justify with evidence:

Prose/Design Quality Axes (absorbed from progressive-harsh-review)

A skill.md review must also judge whether it is a well-written, sensible artifact for a human -- not just whether an LLM can execute it safely. Score these five axes (0.0-10.0) using progressive-harsh-review's persona rule, per-persona weights, aggregation and critical veto verbatim (its "Persona dimension table" section, NOT the generic "Step 1: Dispatch Review" fallback). Skill files are reversible artifacts, so by PHR's rule the combined reviewer scores them as one persona (SeniorArchCritic weights); run the 3-persona ensemble only when the change is irreversible by PHR's definition:

Aggregation: one persona -> its weighted score IS the Prose/Design score. Ensemble -> each sub-persona scores all five axes with its OWN weights, then the three are averaged equally (PHR's Step 3 rule).

Critical veto (verbatim from progressive-harsh-review): if ANY sub-persona scores Correctness or Operational Risk <=4 AND cites a specific defect (not a general concern), that is an automatic REJECT regardless of the weighted mean. An unrecoverable-failure-style finding MUST be scored on Operational Risk -- not Blind Spots alone -- to be veto-eligible; scoring it only on Blind Spots bypasses the veto gate.

Combining both scorecards into one top-level Verdict: use the WORSE of what either implies, never an average.

• LLM-Execution critical veto: any unresolved S0 finding forces REJECT regardless of both scorecards' means -- an execution-safety finding this severe is never merely "at least MAJOR REVISIONS REQUIRED".
• Prose/Design's own critical veto (above) fires -> REJECT.
• Prose/Design weighted mean <7 (PHR's REJECT band) -> at least MAJOR REVISIONS REQUIRED, regardless of S0-S3 findings.
• Prose/Design weighted mean 7 to <8 (PHR's PASS_WITH_FIXES band) -> at least PASS WITH RISKS.
• Otherwise, follow the worse of: highest unresolved severity (S1 present -> at least MAJOR REVISIONS REQUIRED; S2 only -> at least PASS WITH RISKS; S3-only/none -> PASS eligible) and the Prose/Design band above.

Reviewer Dispatch

Obey tools/review-preflight.py. Only REVIEW_REQUIRED dispatches, carrying SPP_REVIEW_CLASS=skill SPP_REVIEW_SNAPSHOT=<strategy.snapshot>; otherwise reuse, wait or stop.

Default: ONE combined reviewer covers Checks A-F and Prose/Design. Its mandatory placement verdict gives file:line and answers whether this is the right place or a simpler root cause exists; omission is incomplete. Provide changed files, registered fence output and cited reference.md sections once. The reviewer retains repo access without repeating supplied work.

Add a specialist (start-points and questions in reference.md) only when its signal is in the diff:

Runtime Determinist (check A) and Context Efficiency Examiner (token pressure) are the combined reviewer's own lenses, not separate agents.

Re-review after fixes: continue the same reviewer and send only the delta -- files changed since the reviewed commit (sentinel_scope_unchanged, tools/lib/sentinel-scope.sh) -- stating that its earlier input is superseded for those files. If it cannot be continued, a fresh reviewer gets the COMPLETE prior findings verbatim from the run envelope plus the delta; a summary is not acceptable input. (Measured 2026-09-20: a continued reviewer's re-review round cost ~5k tokens; a fresh reviewer cost 65-87k.)

Mandatory Checks

You MUST inspect these six areas and report concrete findings -- full flag lists for each are in reference.md. If a category has no applicable content in the artifact under review (e.g., no shell/tool-wrapper code in a pure-prompt skill), state that explicitly -- "N/A -- no shell/tool-wrapper content in this artifact" -- rather than fabricating a finding or silently omitting the section.

• A. Instruction Determinism -- vague verbs, ambiguous trigger/routing precedence, missing pass/fail thresholds
• B. Shell and Runtime Portability -- bashisms, GNU/BSD incompatibilities, unsafe quoting, fragile paths, weak cleanup. Embedded fenced examples in the skill.md/reference.md itself are in scope too -- run tools/test-all.sh --check ci:shell-tests-full-corpus-fence-scan-all-skills-md (see reference.md for why this matters and its known limitation).
• C. Tool Contract Safety -- implicit tool selection, under-specified parameters, unparseable output, unvalidated side effects
• D. Failure-Mode Resilience -- missing stop-and-report rules, looping retries, asserted-not-verified success
• E. Cross-Agent Interoperability -- Claude-only behavior assumed universal, unequal Cursor/Augment support
• F. Test Realism -- string-grep-only tests, no idempotency/absent-tool/adversarial coverage

Diff-Sensitive Focus Map

Apply extra scrutiny based on changed paths:

• skills/** -> trigger precision, output format, token cost, invariants, routing clarity
• tools/**, mcp/** -> argument validation, parseability, safety boundaries, failure semantics
• install*.sh, setup/**, scripts/** -> portability, idempotency, cleanup, environment assumptions
• .ai-guidance/** -> same scrutiny as AGENTS.md itself (it's AGENTS.md content split out on a line-count limit, not a different audience)
• AGENTS.md, CLAUDE.md, CODEX.md, COPILOT.md, GEMINI.md, AGENT.md (any path depth), manifests -> cross-agent drift and unsupported universal claims
• tests/** -> realism of execution-path coverage, not just assertion count

Required Output Format

Produce all sections in order per the template in reference.md -> Required Output Format. Load that section before producing output.

Evidence Requirement (MANDATORY)

A finding is a claim about the artifact. A claim without a way to check it is indistinguishable from a guess, and a high verdict built on unchecked claims is worse than no review at all -- it looks rigorous while catching nothing. Every finding AND every clean-dimension verdict ("no issues found in X") MUST carry a JSON evidence block (schema, worked example, expectation types, and forbidden command patterns: see reference.md -> "Evidence Schema"). A finding or clean-dimension verdict with no evidence block at all is treated identically to "verifiable": false -- capped, not rejected, but never counted as confirmed.

Reviewer Conduct

• Be tough, terse, and specific.
• Do not praise unless it clearly reduces execution risk.
• Do not spend time on style commentary unless it affects agent behavior, and do not call something safe because it is elegant.
• Prefer explicit evidence from the diff or repository state.
• If no diff is provided, inspect the effective implementation and infer the real behavior from the files.
• Fix economy. Every recommended fix is as short as its severity allows -- an S3 fix in one sentence, an S2 fix in three or fewer; a fix that restates content already in the skill is not a fix. Sweep the sentences the recommendations would add and drop what does not change agent behavior. If the review's own recommendations would grow the skill more than ~15% with no S0/S1 finding driving it, dock Context Efficiency and recompute the Prose/Design aggregate -- a review that bloats the skill it audits has failed on its own terms.

Failure Modes

Enforcement Status

Gate 6 requires .llm-skill-review-cleared v2 for skills/*.md, .ai-guidance/*.md, and AGENTS.md-family files, and supersedes PHR/code-review for those classes (tools/md-files-changed.sh LLM_OWNED_REGEX). Pass (ADR-003): verdict PASS|PASS_WITH_RISKS, unresolved_s0_s1=0, non-vacuous clean_dimensions, evidence_replay=ok (or bypassed with PASS only). --min-score is Prose/Design mean as sentinel metadata (mean=) — Gate 6 does not floor-compare it. Envelope details: reference.md "Enforcement Detail". Non-.md under skills/ stays code-review's job.

NEVER write .llm-skill-review-cleared directly. Only the native script writes it. Gate 6 requires v2|SHA|VERDICT|TIMESTAMP|mean=N|unresolved_s0_s1=0|evidence_replay=ok; manual files are rejected. This is a recurring failure mode.

Sentinel write: findings need severity; the envelope needs "head_sha" equal to the commit being cleared; at least one clean_dimensions entry needs replayable evidence ({"evidence":{"command":"...","verifiable":true}}) — a bare string or an all-verifiable:false set is refused as vacuous. Then:

tools/review-envelope.py init --kind skill-review  # binds head_sha
# add-clean, add-finding, resolve: each runs its command first
tools/review-envelope.py set --kind skill-review --verdict PASS --mean "<Prose/Design-mean>" && tools/review-envelope.py check --kind skill-review
tools/run-llm-skill-review.sh --verdict PASS --min-score "<Prose/Design-mean>"

--min-score = the Prose/Design score. AGENTS-family files need this gate alone (not also PHR). Unsure? tools/which-gate.sh <path>.