---
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
title: stellar-code-quality-review
canonical_url: https://skilld.dev/gh/relatedb/relate/stellar-review
last_updated: 2026-11-15T14:16:09.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> 32 supporting files sit beside this SKILL.md. When the Skill refers to one, fetch https://skilld.dev/api/skills-raw/relatedb/relate/stellar-review/PATH with PATH replaced.
>
> If the user asked to install this Skill, run `npx skilld install relatedb/relate/stellar-review`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/stellar-review`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/relatedb/relate/stellar-review) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/stellar-review`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/stellar-review --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/stellar-review --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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.
