summarize-subsystems

Summarize subsystems (community summaries)

Cluster the base code graph into subsystems (by module path) and write a short, grounded

summary for each, persisted for ask / PR-walkthrough to use as a cheap high-level prior. This

skill reads code and writes summaries to the reviewer store; it does NOT modify code or post to

GitHub.

Always write summaries and answer the user in Russian (the project language), regardless of this

file's language. Tool calls, code identifiers and path:line stay verbatim.

Tools

<!-- include: _common/tool-usage.md -->

Plus list_subsystem_clusters, get_subsystem_summary_work, get_file_skeletons,

index_subsystem_summary, prune_subsystem_summaries and backfill_summary_embeddings

(reviewer MCP). File-summary jobs read source ONLY through get_file_skeletons; the harness

Read is not used on source files in this skill.

Pipeline

1. Resolve repo/branch.

<!-- include: _common/branch-selection.md -->

1. List clusters (compact, paginated). Walk every page:

call list_subsystem_clusters(repo, branch, compact=True, limit=100), then repeat with

offset += 100 while the response has has_more == true. Stop only when has_more == false —

a partial walk is not a full pass. Empty / note about an empty

index → tell the user (in Russian) to run rag-reviewer:sync-codebase first, then stop.

Every page carries the same whole-set fields: depth (the applied cluster depth),

layout_token (server-owned identity of the effective default depth plus sorted per-prefix

overrides), depth_source (env | .review.yml | arg), deferred (stale clusters held

back this pass under the cost cap, env SUMMARY_REBUILD_CAP), deferred_files (their pending

file jobs), orphans (stored summaries whose cluster_key is no longer a current cluster),

and total_clusters (non-deferred clusters across the whole set, page-independent).

The compact listing deliberately does not carry file-level data: each cluster gives

cluster_key, num_members, source_hash, stale, bootstrap, full_rebuild,

reused_files and the numeric counters added, changed, removed, moved — no paths and

no fingerprints. That keeps the listing O(clusters) instead of O(files). Per-cluster file

detail comes from get_subsystem_summary_work in step 5.

Accumulate across pages: expected_source_hashes = {cluster_key: source_hash} from every

returned cluster, and the counter totals for the preflight. Save the layout_token; these

exact list-snapshot values are required for finalization.

1. Preflight — echo the applied depth and ask for confirmation (gate the run). BEFORE summarizing,

show the user (in Russian):

• the applied depth and where it came from (depth_source: env SUMMARY_CLUSTER_DEPTH, the repo's

.review.yml, or an explicit arg);

• how many clusters there are (total_clusters) and at what path level — e.g. «depth=2 → 15

кластеров уровня reviewer/index» — sampling a few cluster_keys from the accumulated pages;

• how many are stale vs fresh, how many require bootstrap, plus deferred clusters and

deferred_files (held back by the cap). Compute these from the accumulated compact records —

the added/changed/removed/moved counters are enough; never re-list in full format.

• If orphans > 0, warn: the depth changed or modules were removed, so N summaries are orphaned;

a full (uncapped) pass will rebuild and prune them.

• If any cluster has bootstrap == true, explain that this is the first post-upgrade fragment

bootstrap: all current files in selected clusters get fragments, cap-deferred clusters wait for

later passes, and old cluster summaries remain available until their replacements are stored.

• State the invariant explicitly: cluster_key and the layout identity depend on the whole

layout policy — the default depth, every depth override, **and the summary_paths.ignore

clustering filter (which keeps test trees out of summaries without touching the review

index)** — so changing any of them triggers a full rebuild of every summary (old-layout

summaries orphan and get pruned).

Then ask the user to confirm before running. If they decline, stop without summarizing or pruning.

1. Choose the summary model (only if work is selected). Select clusters where

stale == true OR bootstrap == true; full rebuilds already arrive as stale. A subsystem summary

is a coarse, high-level prior — a small/cheap model is appropriate, and reviewing on an expensive

model burns tokens. Ask the user which model tier to use for writing summaries, defaulting to a

cheap tier (e.g. Haiku/Sonnet/Fable). Remember the choice for this run. If no cluster is selected,

skip this step. Where model override is supported, dispatch a subagent on the chosen model.

1. Build selected clusters from file fragments. Initialize run totals for created, reused,

removed, moved, raced, and embedded; initialize deferred from step 2. For each selected

cluster:

1. Call get_subsystem_summary_work(repo, branch, cluster_key, source_hash) once, passing the

cluster's listed source_hash. If ready=false, count the cluster as deferred/raced, increment

raced, and continue without jobs or persistence.

1. Let pending work be exactly added_files + changed_files. Split it into **batches of at

most 15 paths**, preserving order, and dispatch exactly one file-summary job per batch on

the chosen model — and no other source-reading jobs. Each batch prompt must name only its

own paths and tell the job to fetch their skeletons with a single

get_file_skeletons(repo, paths, branch) call. A job must read nothing else: no harness

Read of a source file, no read_file. The skeleton is deliberately the whole input —

it is exactly the material a fragment's freshness hash is computed from, so a summary

derived from it cannot silently go stale. A skeleton value that starts with ( or contains

the (…усечено) truncation marker is not source: the job must not summarize it. Treat that

path as not done for this batch and count it toward deferred. The job returns one Russian

result per path: {path, summary, provenance}. A job must never compute, guess, or return a fingerprint:

that value is server-side and the orchestrator supplies it. If a job returns a path

outside its batch, or omits a path of its batch — other than a path already treated as not

done for this batch under the note/truncated-skeleton rule above — discard that batch's

results and re-dispatch that batch once; on a second mismatch count the cluster as deferred,

increment raced, and persist nothing for it. The orchestrator and every job must not read

unchanged source files. If per-subagent model override is unavailable, generate the same

per-file results inline and note that fallback in the report.

1. Build the ordered reused/moved/new fragment texts by merging reused_fragments,

moved_files, and the new file results, then sorting by path. The orchestrator attaches each

new fragment's fingerprint by joining on path with the authoritative added_files /

changed_files entries of the get_subsystem_summary_work response — never from a job's

answer. Dispatch exactly one cluster

composer on the chosen model with only those ordered fragment records; do not pass files,

top_symbols, or source text. Its prompt must say: composer must not call Read and must

not make source-code claims absent from the fragments. It returns {title, summary} in

Russian: a one-line subsystem title and a compact paragraph about responsibilities, key

symbols, and invariants supported by the fragments.

1. Persist the bundle:

`index_subsystem_summary(repo, branch, cluster_key, title, summary, source_hash,

fragments=[new file results])` (the fingerprint-enriched records from 5.3). Pass only the

newly generated pending-file results in

fragments; reused and moved fragments are committed server-side. If the response has

stored=false, count the cluster as deferred/raced, increment raced, and must not count it as success

or add its metrics. For stored=true, add returned created, reused, removed,

and moved to the run totals, and add one to embedded when its embedded is true.

1. Prune orphaned summaries (only on a full pass). If the pass was full — you walked every page

to has_more == false, deferred == 0, you have raced == 0, and you did NOT pass an explicit

depth/cap override (so the accumulated clusters covered every current cluster) — call

prune_subsystem_summaries(repo, branch, layout_token, expected_source_hashes) with the exact

values saved from step 2. The server re-derives the layout/hashes and verifies complete

same-generation fragment coverage under its branch lock before deleting summaries whose

cluster_key is no longer current. If prune returns completed=false, count the prune as

raced/partial, increment raced, do not treat depth/layout as finalized, and report its

deferred/note; do not add prune metrics. For completed=true, accumulate both returned

pruned and fragments_pruned. On a partial pass (deferred > 0,

any race, or an override) skip pruning — deferred clusters are not orphans and an incomplete

bootstrap must not finalize depth state — and say so in the report (mirrors sync_board --limit).

Pagination is not an override: paging through the listing with offset/limit still yields

a full pass, as long as you walked to has_more == false.

6.5. Backfill summary embeddings (every pass). Call backfill_summary_embeddings(repo, branch) so

any summaries still missing an embedding (older summaries written before vectorization, or where a

prior pass's Voyage call failed) become searchable by proximity. It embeds from stored title+summary

(no LLM), is idempotent (a warm corpus embeds nothing), and is fail-soft. Add its returned

embedded count to the run total.

1. Report (Russian). The applied depth + depth_source; clusters stored vs skipped-as-fresh;

cap-deferred clusters/files and optimistic raced clusters (the report's deferred/raced total);

fragment metrics created, reused, removed, and moved; summaries pruned and

fragments_pruned, or that pruning was skipped on a partial pass; and total embedded. Never

silently truncate. If file summaries or composers were written inline (no model override), say so.

Grounding (hard rule)

<!-- include: _common/anti-hallucination.md -->

Each new file fragment must reflect exactly its own pending file's skeleton and nothing else's. Cluster composers

ground only on provided fragments and never read source. If the fragments leave a cluster unclear,

say so briefly rather than guessing.

Notes

• Precondition: base index built (reviewer index). Re-running is incremental at file-skeleton

fingerprint granularity: unchanged source files are not read or summarized again.

• Read-only on code and GitHub; only writes summaries to the reviewer store.

Reporting a reviewer defect

<!-- include: _common/bug-reporting.md -->