Skip to content
Skills Library
Programming · Review & audit

stellar-code-quality-review

/stellar-code-quality-review

Strict maintainability review — abstraction quality, file size, spaghetti growth. Runs as a deterministic incremental pipeline (facts → ledger scope → briefs → focused passes → scripted verdict) so every blocker and medium surfaces in round 1 and untouched code never re-produces findings. Use for a stellar code quality review, deep quality audit, or harsh maintainability review.

Repository
relate ↗
Licence
Apache-2.0
Last repository change
13.11.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
33
Scripts
25
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 25 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: tools/briefs.py, tools/facts.py, tools/fileout.py, tools/incremental.py, tools/ledger.py, tools/linear_queue.py, tools/nightshift.py, tools/pass_models.py, tools/passstats.py, tools/post.py, tools/recurrence.py, tools/similar.py, tools/tests/helpers.py, tools/tests/test_agents_sync.py, tools/tests/test_briefs.py, tools/tests/test_facts.py, tools/tests/test_last_head_fetch_guard.py, tools/tests/tes

What it does and when to use it

Strict maintainability review — abstraction quality, file size, spaghetti growth. Runs as a deterministic incremental pipeline (facts → ledger scope → briefs → focused passes → scripted verdict) so every blocker and medium surfaces in round 1 and untouched code never re-produces findings. Use for a stellar code quality review, deep quality audit, or harsh maintainability review.

Original author description

Strict maintainability review — abstraction quality, file size, spaghetti growth. Runs as a deterministic incremental pipeline (facts → ledger scope → briefs → focused passes → scripted verdict) so every blocker and medium surfaces in round 1 and untouched code never re-produces findings. Use for a stellar code quality review, deep quality audit, or harsh maintainability review.

How it works

  1. Step 0 — facts, ledger, scope, briefs (scripts only)
  2. Step 1 — gates (no model tokens)
  3. Step 2 — dispatch the passes (parallel sub-agents)
  4. Step 3 — assemble findings.json
  5. Step 4 — hand off
  6. What changed from the old skill (for anyone surprised)
Original SKILL.md headings · 120 lines, 1,610 words
SKILL.md preview
---
name: stellar-code-quality-review
description: Strict maintainability review — abstraction quality, file size, spaghetti growth. Runs as a deterministic incremental pipeline (facts → ledger scope → briefs → focused passes → scripted verdict) so every blocker and medium surfaces in round 1 and untouched code never re-produces findings. Use for a stellar code quality review, deep quality audit, or harsh maintainability review.
disable-model-invocation: true
---

# Stellar Review

Unusually strict review of implementation quality, maintainability, and abstraction health. Push for **ambitious** restructurings — "code judo" moves that preserve behavior while making the code dramatically simpler, smaller, and more direct. Delete complexity; don't rearrange it.

This review is a **pipeline** (ADR-0271), not a reading. Scripts own everything mechanical — what changed, how big things are, where the branches/casts/fallbacks are, which units look alike, what was already decided. Model tokens buy exactly one thing: per-unit judgment over pre-digested briefs. Do not improvise around the steps, and never review a raw diff — that is the low-recall mode this pipeline replaced.

The tools live next to this file: `tools/facts.py` (git-side extraction), `tools/units.py` (language machinery), `tools/similar.py` (near-duplicates), `tools/ledger.py` (cross-round state), `tools/incremental.py` (stale-ledger-proof anchoring diff, ADR-0292), `tools/nightshift.py` (night-shift queue planner), `tools/briefs.py` (pass briefs), `tools/pass_models.py` (CI per-pass model config, ADR-0302), `tools/post.py` (GitHub posting) — pure Python 3 stdlib. Pass mandates live in `passes/`, doctrine in `references/`. Runtime state lives in `.stellar/` (gitignored).

## Step 0 — facts, ledger, scope, briefs (scripts only)

**Local pre-push rounds ALWAYS run the script — never a hand-rolled subset of these steps.** The abbreviated hand-copy (facts → scope → briefs, skipping the ledger fetch and the dependency-dirty expansion) is exactly the divergence that let CI keep finding findings the local round never saw. One command, from the repository root, on the branch to review:

```sh
.github/scripts/stellar-prep.sh local [--quick] [PR_NUMBER]
```

`PR_NUMBER` is optional: given → that PR's ledger is fetched from its summary comment; absent → the PR for the current branch, if one exists; no PR at all → round-1 semantics (no ledger fetch, empty ledger). The script derives the inputs CI's `model` mode reads from its env — base per the SCOPE RULE below, head = HEAD — and runs the identical pipeline body (ledger → facts → docs-only gate → scope → dependency-dirty expansion → incremental diff → briefs), writing `.stellar/facts.json`, `.stellar/scope.json`, `.stellar/briefs/`. CI's `model` mode and the local round are the same code path: `stellar-prep.sh` is the one entry point. Then dispatch the four passes over `.stellar/briefs/` (Step 2).

`--quick` is the cheap mid-work sanity check: delta-only scope (the dependency-dirty expansion is skipped) and one brief per pass (no sharding, however big the round). Model tiers are unchanged — the tier guidance and `STELLAR_MODEL_*` overrides below apply as-is; the script never configures models. **Quick is a PRE-FILTER, never a gate — quick catches what the delta touches; the full round (carried ledger + expansion + shards) is still mandatory before every push.**

What each mode catches:

- **Full round (the mandatory pre-push gate)** reviews the delta PLUS the carried ledger's earlier-round units PLUS the dependency-dirty expansion (callers/callees of changed units) — approximately what CI's round will judge. Cost: more units, sharded briefs, all four passes at their configured tiers — the expensive but CI-faithful shape.
- **Quick round (mid-work pre-filter)** reviews ONLY the delta's changed units, one shard per pass — it catches what your own edit touches (structure/branching shape in the code you just wrote) and misses anything CI anchors via earlier rounds or dependency expansion (the observed failure class: findings on pre-existing callers pulled into scope). Cheap, fast, NOT a gate.

A clean quick round does NOT predict a clean CI round; a clean full round is the best local predictor of CI's verdict — and even the full round differs from CI by model pinning (CI's `STELLAR_MODEL_*` secrets), so a local green is strong, not identical.

The rest of this section is the manual reference — the expansion of exactly what the script runs (and what CI's env-driven `model`/`post` modes do with workflow-provided inputs), kept for reading, not for hand-copying:

```sh
TOOLS=.agents/skills/stellar-review/tools
mkdir -p .stellar

# facts (CI passes --base/--head from the PR payload; locally they default
# to merge-base HEAD origin/main → HEAD)
#
# SCOPE RULE (anti-balloon): when .stellar/ledger.json exists and its
# last_head is an ancestor of HEAD, ALWAYS pass --base <last_head> --head
# HEAD. The main merge-base default is for round 1 (no ledger) only — using
# it on an existing PR re-judges the entire PR diff and balloons the scope
# (891+ units, hours of pass time). After a force-push/rebase (last_head
# not an ancestor of HEAD), pass --base <merge-base HEAD origin/main> — never
# the merge-base of the old and new heads, which re-includes main's advance.
python3 $TOOLS/facts.py --out .stellar/facts.json

# ledger: CI fetches it from the PR summary comment; locally it is a file
# CI:   python3 $TOOLS/post.py fetch-ledger --repo $REPO --pr $PR --out .stellar/ledger.json
# local: .stellar/ledger.json already exists from the last round, or not (round 1)

python3 $TOOLS/ledger.py scope --facts .stellar/facts.json --ledger .stellar/ledger.json --out .stellar/scope.json

# dependency expansion: if scope.json lists dependency_dirty_files, rerun
# facts with them included, then rerun scope:
jq -r '.dependency_dirty_files[]' .stellar/scope.json > .stellar/expand.txt
# (if non-empty) python3 $TOOLS/facts.py --out .stellar/facts.json --include-units-file .stellar/expand.txt
# (and rerun the scope command above)

# briefs: incremental rounds embed the since-last-round diff; round 1 omits it
LAST=$(jq -r '.last_head // empty' .stellar/ledger.json)
HEAD=$(jq -r '.head' .stellar/facts.json)
if [ -n "$LAST" ] && [ "$LAST" != "$HEAD" ]; then
  # never raw `git diff $LAST $HEAD`: after a force-push/rebase LAST is stale
  python3 $TOOLS/incremental.py --facts .stellar/facts.json --ledger .stellar/ledger.json --out .stellar/diff-incremental.patch
  python3 $TOOLS/ledger.py brief --facts .stellar/facts.json --scope .stellar/scope.json --diff .stellar/diff-incremental.patch --out .stellar/briefs
else
  python3 $TOOLS/ledger.py brief --facts .stellar/facts.json --scope .stellar/scope.json --out .stellar/briefs
fi
```

## Step 1 — gates (no model tokens)

- `facts.has_code_changes` is `false` → docs/CI-only diff. Stop. (CI: the workflow already ran `post.py noop`.)
- `scope.stats.units_in_scope` is `0` **and** `scope.resolve_checks` is empty → nothing new to judge. Write `{"version": 1, "findings": [], "resolutions": [], "coverage": [], "notes": "nothing changed since last round"}` to `.stellar/findings.json` and go to Step 4. Open findings from earlier rounds are carried by the ledger — the poster re-states them; you do not.

## Step 2 — dispatch the passes (parallel sub-agents)

For **each** file in `.stellar/briefs/` (`brief-structure[-N].md`, `brief-branching[-N].md`, `brief-boundaries[-N].md`, `brief-comparison.md`), dispatch one sub-agent — the `stellar-structure`, `stellar-branching`, `stellar-boundaries`, `stellar-comparison` agents are defined in this repository (`.opencode/agents/` / `.claude/agents/`). Dispatch all of them in parallel. Prompt per agent:

> Stellar review round <N>. Your brief is `.stellar/briefs/<file>` — read it fully, then follow your standing instructions (mandate + doctrine + JSON output). Return only your JSON document.

Never merge two briefs into one dispatch, and never dispatch a pass without its brief — the isolated contexts and pre-digested inputs are what make the passes exhaustive and fast.

If a pass agent fails to dispatch or errors, stop and report the failure — never assemble or post a partial review; a missing pass is not an empty pass.

MODEL TIERS (cost/speed): the passes are mechanical checklist reads against pre-digested briefs.

Per-pass model overrides (ADR-0302): `STELLAR_MODEL_<PASS>` (`STELLAR_MODEL_STRUCTURE`, `STELLAR_MODEL_BRANCHING`, `STELLAR_MODEL_BOUNDARIES`, `STELLAR_MODEL_COMPARISON`) overrides that pass's sub-agent model; unset or empty = no override — locally the tier guidance below applies, in CI the pass inherits the run-level model.
- **CI**: the workflow applies each non-empty value as per-agent OpenCode config before the run — `tools/pass_models.py` writes it verbatim (an OpenCode `provider/model`) to `agents.stellar-<pass>.model` in `~/.config/opencode/opencode.json` — so the CI dispatcher takes no model action.
- **Local**: a dispatcher that can set a per-dispatch model runs `printenv STELLAR_MODEL_<PASS>` before dispatch and passes a non-empty value as that pass's model, in the dispatcher's own model syntax (OpenCode `provider/model`, a Claude Code alias such as `haiku`).

Tier guidance: dispatch `stellar-boundaries` and `stellar-comparison` on the cheapest fast model your dispatcher supports (e.g. `model: haiku`); `stellar-branching` on the mid model (e.g. `model: sonnet`); keep `stellar-structure` on the default/strong model — decomposition and 1k-line judgment is the one pass that genuinely needs it. A finding dropped by a cheap pass is usually caught by its siblings or by CI's full-strength round; the cost asymmetry favors cheap local passes.

## Step 3 — assemble findings.json

Collect each agent's JSON document. Concatenate `findings`, `resolutions`, and `coverage` arrays. Write exactly one file, `.stellar/findings.json`:

```json
{"version": 1, "findings": [...], "resolutions": [...], "coverage": [...], "notes": ""}
```

Sanity-check before writing: every finding has `area`, `severity` (`blocker|medium|nit`), `path`, `start_line`, `quote`, `why`, `remedy`; every finding's `unit` (when present) is a unit the scope actually assigned; no finding quotes code from a sealed unit; in incremental rounds, every finding's lines intersect the incremental diff hunks. Drop violations — they are process errors, not findings (the poster drops them anyway: scope membership and incremental anchoring are script-enforced, ADR-0275). This file is the **only** file you may write.

## Step 4 — hand off

- **CI**: stop here. The workflow runs `post.py`, which rolls the ledger, posts one review with all inline comments, derives the verdict, and updates the summary comment.
- **Local**: roll the ledger and print the report yourself:
  ```sh
  python3 $TOOLS/ledger.py update --facts .stellar/facts.json --ledger .stellar/ledger.json \
      --findings .stellar/findings.json --scope .stellar/scope.json
  ```
  Then print: round number, scope stats, findings grouped by severity (blocker → medium → nit, with `path:lines`, why, remedy), resolution outcomes, and the approval-bar verdict (`references/full-checklist.md`). Direct, serious, demanding tone; a small set of well-evidenced findings beats a wall of nits — but nothing medium or higher is ever held back.

## What changed from the old skill (for anyone surprised)

- No `git diff` reading, ever. Facts and briefs are pre-digested and identical every round for the same code.
- The verify pass is gone; the **comparison** pass catches the same defect class (inconsistency between similar sites) from similarity groups instead of a fifth full read.
- Round 2+ reviews only what changed since round 1 (plus signature-affected dependents and resolution checks). Everything else is sealed — new findings on untouched code are a process violation.
- Posting and verdict are scripts. The model writes `.stellar/findings.json` and nothing else.
Files in this package (33)
  • SKILL.md 12 KB
  • passes/boundaries.md 3 KB
  • passes/branching.md 3 KB
  • passes/comparison.md 2 KB
  • passes/structure.md 2 KB
  • references/finding-schema.md 3 KB
  • references/full-checklist.md 9 KB
  • references/severity-rubric.md 2 KB
  • tools/briefs.py 15 KB
  • tools/facts.py 19 KB
  • tools/fileout.py 1 KB
  • tools/incremental.py 3 KB
  • tools/ledger.py 24 KB
  • tools/linear_queue.py 18 KB
  • tools/nightshift.py 11 KB
  • tools/pass_models.py 5 KB
  • tools/passstats.py 3 KB
  • tools/post.py 35 KB
  • tools/recurrence.py 1 KB
  • tools/similar.py 2 KB
  • tools/units.py 12 KB
  • tools/tests/helpers.py 3 KB
  • tools/tests/test_agents_sync.py 2 KB
  • tools/tests/test_briefs.py 7 KB
  • tools/tests/test_facts.py 8 KB
  • tools/tests/test_last_head_fetch_guard.py 4 KB
  • tools/tests/test_ledger.py 17 KB
  • tools/tests/test_linear_queue.py 13 KB
  • tools/tests/test_local_round_entry.py 9 KB
  • tools/tests/test_model_env_drift.py 12 KB
  • tools/tests/test_nightshift.py 8 KB
  • tools/tests/test_pass_models.py 7 KB
  • tools/tests/test_post.py 33 KB

Versions

The database has no other skills named stellar-code-quality-review.

Database snapshot: 13.11.2026 · package version 7f82734ca6cc (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90code-review
    Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a code review, deep code quality audit, or especially harsh maintainability review. Only use when explicitly asked to review; never during implementation.
  • 90code-review
    Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a deep code quality audit or an especially harsh maintainability review.
  • 100thermo-nuclear-code-quality-review
    Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review.
  • 90extreme-code-quality-review
    Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for an extreme code quality review, deep code quality audit, or especially harsh maintainability review.
  • 100thermo-nuclear-code-quality-review
    Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review.
  • 100nuke-review
    Run an extremely strict maintainability review for abstraction quality, giant files, and spaghetti-condition growth. Use for a thermo-nuclear code quality review, thermonuclear review, deep code quality audit, or especially harsh maintainability review.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.