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

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.

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

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

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

5. 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.
   2. 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.
   3. 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.
   4. 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.

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

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

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