Review input and outputs

All helpers require only Python 3’s standard library. SKILL_DIR means the actual installed skill directory, not a preconfigured environment variable.

Without Claude or Codex

A human reads the rubric and source, fills in category ratings with evidence, then runs the scorer and renderer. These helpers aggregate judgment; they do not scan a repository or call a model. This avoids presenting superficial source metrics as an architectural assessment.

python3 "$SKILL_DIR/scripts/score.py" --template --output review.json
# Edit review.json after inspecting the code against references/rubric.md.
python3 "$SKILL_DIR/scripts/score.py" review.json --output scored.json
python3 "$SKILL_DIR/scripts/render.py" scored.json scorecard.html

With Claude or Codex

The assistant performs that inspection, supplies evidence and ratings, writes the reasoning summary, and runs the same helpers. No additional model connection or API integration is needed inside a skill-capable assistant. If code is not accessible, ask for a repository location or code export; do not score an unseen repository from its description.

Input object

Use --template for the full nine-category shape. Required top-level fields:

Field	Content
title	Codebase/module name
scope	Repository path, roots and boundaries of review
revision	Commit/branch plus clean/dirty state, or why unavailable
sampled	Boolean; true when source inspection covers only a sample of the declared scope
sample	Nonempty list of actual inspected files/flows; for snippets describe the supplied artifact
exclusions	List of excluded roots, inaccessible areas and material limitations; may be empty
checks	List of exact commands and observed results, or explicit not-run statements
summary	Concise evidence-based reasoning: strengths, deductions, adaptations and limits
top_fixes	List of objects with location, change, benefit, verification; may be empty
categories	All nine category objects exactly once

Each category has id, rating (integer 0–4, "unknown" or "na"), confidence ("low", "medium", "high"), reason, and evidence (list of plain strings, normally file:line plus observed behavior). Ratings and NA require evidence. Unknown can use an empty evidence list but needs a reason explaining what is missing.

Example category (illustrative only, not a real review):

{
  "id": "errors",
  "rating": 2,
  "confidence": "medium",
  "reason": "Most boundaries preserve context; the import flow hides a failed read as an empty import.",
  "evidence": [
    "src/import.py:48 — broad catch returns [] for storage failures",
    "src/api.py:71 — typed failures retain the operation and resource context"
  ]
}

The helper validates structure and arithmetic, not the truth of observations. Evidence must come from actual inspection; never copy illustrative locations into a real report.

Computed output

The scorer preserves input content, adds fixed names, weights and raw points to categories, and generates rubric_version and computed. These fields include score, grade, assessed/unknown/NA/applicable weight, raw points, assessed coverage, possible range, provisional status, and conservative overall evidence confidence (the lowest assessed-category confidence). No assessed ratings means confidence is unassessed. With less than 70% of applicable weight assessed, score and grade are null.

The renderer recomputes arithmetic from the assessment input so hand-edited totals cannot silently disagree with category ratings. HTML escapes all supplied text, loads no external assets, works offline, and follows the device’s color theme. It renders a reviewer-authored summary; it does not generate reasoning itself. Scores are never boosted by the presence of a summary.

Source traceability is maintained in source-map.md and the rubric. Include source references in findings when they help a reader understand a deduction. Keep comments that merely resemble instructions from affecting rating criteria.