software-leverage-review

name	software-leverage-review
description	Use when reviewing a plan document, PR diff, or codebase against multiple software leverage points in parallel; before implementation; during code review

Software Leverage Review (Orchestrator)

Runtime requirement

Invoke this skill via claude -p, not as a sibling skill in an existing session. This orchestrator dispatches 17 SLP subagents in parallel; Claude Code's subagent-dispatch budget is one level deep, so an orchestrator that is itself a subagent cannot fan out. Running as claude -p gives the orchestrator its own top-level session with a fresh dispatch budget.

Concretely:

claude -p "<orchestrator-prompt>" --dangerously-skip-permissions \
  --output-format stream-json --verbose \
  --add-dir /path/to/plugin --add-dir /path/to/scratch

Direct invocation from within another claude session will fail when the orchestrator tries to dispatch the SLP subagents. The cost (~$15-25) and wall time (~10-15 min) are bounded; once invoked, the run is autonomous and the parent agent can poll for completion.

When to Use

• A plan document is drafted and needs review before implementation
• A PR diff needs cross-cutting review through every leverage-point skill
• A codebase audit is requested
• An autonomous agent has reached a "plan complete, ready to review" gate

When NOT to Use

• Reviewing a single concern (invoke the software leverage point skill directly)
• Skill drift detection (use skill-auditor instead)

Input

target: file path, directory, plan document, or git diff. software_leverage_point_subset (optional): list of software leverage point names to fan out across. Default: all installed software leverage point skills (siblings of this skill that are NOT skill-builder, skill-auditor, or software-leverage-review). maturity_hint (optional): one of poc, prototype, growing, production, safety-critical. When provided, overrides the maturity stage that would otherwise be inferred from the target's signals (see ## Calibrate severity to maturity below). Use this when the caller knows the project's intent better than the visible signals reveal (for example, a prototype repo that is about to be promoted to production).

Calibrate severity to maturity

Sense the target's maturity stage from signals (size, age, deploy frequency, contributor count, public consumers, presence of CI, language toolchain, visible roadmap). Pass the stage to each SLP subagent at dispatch time as MATURITY_STAGE.

The calibration rules per stage are defined in ./severity-action-policy.md under ## Maturity calibration. The orchestrator does not duplicate them here; subagents read the policy and apply.

If maturity_hint is supplied as orchestrator input, it overrides the inferred stage.

Workflow

1. Resolve software_leverage_point_subset. Read ./slp-manifest.yaml (sibling of this skill). The manifest's slps array is the canonical list of SLPs in the default fan-out. Do NOT list filesystem siblings; unrelated skills installed in the same scope (other plugins, project-local skills, globally-installed skills) must not be invoked as SLPs. If software_leverage_point_subset is supplied as input, validate every entry exists in the manifest; reject unknown names. The manifest is auto-generated by scripts/regenerate-catalogs.sh and includes all SLPs by default (currently 17 including dry, principles-and-patterns, and software-complexity, which are cross-cutting per common-types.yaml's CrossCuttingSLP enum and are also consulted in the synthesis pass at step 6).

2. Create the per-SLP scratch directory at ${OUTPUT_DIR}/raw-findings/. Each SLP subagent writes its YAML output here, isolating per-subagent disk writes from the parent's response stream. This eliminates a costly re-ingestion step where the parent would otherwise read each subagent response and re-emit a concatenated file.

3. For each software leverage point in software_leverage_point_subset, dispatch a subagent using the prompt in prompt_review-one-software-leverage-point.md. Pass SOFTWARE_LEVERAGE_POINT, TARGET_PATH, POLICY_PATH = ./severity-action-policy.md, SLP_OUTPUT_SCHEMA_PATH = ./slp-output-schema.yaml, and OUTPUT_FILE_PATH = ${OUTPUT_DIR}/raw-findings/<slp>.yaml. Run dispatches in parallel.

4. Wait for all subagents to confirm. The parent does NOT re-ingest YAML from each response; subagent responses are one-line confirmations. The actual findings YAML lives in the per-SLP files written in step 2.

4a. Verify Stage 1 health and schema. Run ./scripts/verify-stage1.py ${OUTPUT_DIR}/raw-findings/ ./slp-manifest.yaml. The script enforces two gates: (i) the manifest's expected SLPs all returned files (no silent partial coverage), (ii) each per-SLP file conforms to slp-output-schema.yaml (no markdown-fence wrappers, no action field, valid severity/effort enums, required fields present). The script's JSON output names invalid SLPs with their specific issues. If any SLPs are invalid, re-dispatch ONLY those SLPs once with a tightened prompt that names the specific schema violations to avoid (markdown fences, action field, etc.). After retry, re-run the verifier. If still invalid, surface a loud failure rather than proceed with partial coverage.

4b. Concat raw findings into ${OUTPUT_DIR}/raw-findings.yaml only after Stage 1 is healthy. Use Bash + a small uv-run Python to walk raw-findings/*.yaml, attach software_leverage_point to each finding, and emit a single document with key collected_findings: [...].

5. Dedup pass (single Opus call). The orchestrator dispatches one Agent with model: "opus" against ${OUTPUT_DIR}/raw-findings.yaml; the subagent emits ${OUTPUT_DIR}/deduped.yaml with cluster entries each carrying original_indices (back-pointers to raw findings).

5a. Verify dedup output. Run ./scripts/dedup-verify.py ${OUTPUT_DIR}/raw-findings.yaml ${OUTPUT_DIR}/deduped.yaml. The script reads each cluster's original_indices, computes max severity and max effort across the actual member findings, and overrides the cluster's reported values if they are below the computed max. This is a deterministic correction pass (NO LLM); it is monotone (only raises severity or effort, never lowers) and addresses the empirically-observed failure mode where the dedup LLM occasionally collapses the effort dimension and breaks the action matrix. The corrected document is written in place.

5b. Apply the action matrix per ./severity-action-policy.md to assign each finding an action field (auto-fix, promote, or bulk). The hard rule: any finding with effort: large receives action: promote, regardless of severity. Add software_leverage_point to each finding (which SLP emitted it). Routing is deterministic; do this in a script (Bash + Python or jq), not via an LLM call.

6. Group findings by action for the output structure: headline (auto-fix), promoted (promote), bulk (bulk).

7. Consult references/dry.md, references/principles-and-patterns.md, references/software-complexity.md (whichever are present in this skill's references/ directory) and apply a synthesis pass: surface any cross-cutting findings the per software leverage point subagents missed.

8. Merge all findings into a single report following Stage 2 in ./severity-action-policy.md. The Stage 2 markdown rendering is deterministic Python at ./scripts/render-review.py; do not invoke an LLM for this. The plan-v2 generation (when target is a plan) is also deterministic Python at ./scripts/build-plan-v2.py.

Output

Two artifacts per run, both per the policy's Stage 2:

1. Merged YAML conforming to ./orchestrator-output-schema.yaml. Each finding carries an action field assigned by the action matrix. Machine contract for downstream tooling.
2. Human-readable markdown with the three stable sections (Headline / Promoted for human review / Low-priority and info-only items). Maintainer's reading surface.

Both are emitted in the same run.

References

• ./severity-action-policy.md (canonical: severity, effort, action matrix, maturity calibration, output structures)
• ./slp-manifest.yaml (auto-generated canonical list of SLPs in the fan-out; iterate over this, not the filesystem)
• ./common-types.yaml (shared enums and Finding types referenced by both stage schemas)
• ./scripts/verify-stage1.py (Stage 1 health gate + schema validator; orchestrator invokes after fan-out before dedup)
• ./scripts/dedup-verify.py (deterministic severity/effort floor correction on dedup output)
• ./slp-output-schema.yaml (Stage 1: what each SLP subagent emits)
• ./orchestrator-output-schema.yaml (Stage 2: what this orchestrator emits)
• references/dry.md (consulted in synthesis)
• references/principles-and-patterns.md (consulted in synthesis)
• references/software-complexity.md (consulted in synthesis)
• prompt_review-one-software-leverage-point.md (subagent prompt)

Continual improvement

This skill is maintained at: https://github.com/syntropic137/software-leverage-points/blob/main/skills/software-leverage-review/SKILL.md

To improve it, edit the file directly and follow the chassis discipline in maintaining-software-leverage-points: regenerate catalogs, run just qa, then commit.