h-dv/code-index

Watch

Fork 0

project_overview is ~95% operator/plugin admin and ~5% orientation — make orientation the default, admin a detail #522

New issue

Closed

opened 2026-11-09 08:03:47 +01:00 by buildagent · 2 comments

buildagent commented

2026-11-09 08:03:47 +01:00

Member

Summary

project_overview is the first call the docs recommend, and its reply is mostly operator and plugin administration rather than orientation. Measured on this repository (2026-11-09): 35,606 chars ≈ 9–10k tokens, broken down as follows.

Block	chars	share
plugin/package admin (`plugin_activation` 7,256, `package_updates` 6,190, `symbol_blind_extensions` 3,923, `language_ownership` 1,197)	18.5k	52%
`semantics` prose	9.0k	26%
`file_health` (50 rows)	8.2k	23%
orientation content: `languages`, `resolution`, `entry_points`, `top_referenced_symbols`	~1.9k	~5%

(The shares overlap a little, because semantics strings sit inside the admin blocks.)

At the same time, what an agent actually needs is missing. There is no per-directory or per-crate map. entry_points is 20 lib.rs/main.rs paths with no description, and top_referenced_symbols lists join and open. In a 1,500-file repository the agent still has to call repo_map to learn its layout.

package_duplicate_ids also lists every shadowed digest (5 for svelte, 4 for several others). That is useful to an operator and noise to an agent.

Proposal

The default reply is the orientation core: languages and counts, a per-top-level-directory summary (files, symbols, the 3 most-referenced symbols in each), entry points, and index state.
Operator health goes behind detail: "health" (or the existing code-index://project/overview resource): plugin activation, package updates, duplicate ids, file_health, count_basis.
semantics strings appear once per reply in a glossary link, not inside every block.

Acceptance

The default reply is at most 2.5k tokens on this repository.
The health detail keeps every field it has today, and the disclosure registries stay green.

Found by the automated agent-usefulness review (2026-11-09). I reproduced the size in the main session, where the reply was larger still because of the linked worktrees.

Filed from a five-agent review of master @ e3ec6ead (bloat, robustness, agent usefulness, docs, architecture). Every finding was spot-checked in the main session before filing.

## Summary `project_overview` is the first call the docs recommend, and its reply is mostly operator and plugin administration rather than orientation. Measured on this repository (2026-11-09): **35,606 chars ≈ 9–10k tokens**, broken down as follows. | Block | chars | share | |---|---|---| | plugin/package admin (`plugin_activation` 7,256, `package_updates` 6,190, `symbol_blind_extensions` 3,923, `language_ownership` 1,197) | 18.5k | 52% | | `semantics` prose | 9.0k | 26% | | `file_health` (50 rows) | 8.2k | 23% | | **orientation content**: `languages`, `resolution`, `entry_points`, `top_referenced_symbols` | **~1.9k** | **~5%** | (The shares overlap a little, because `semantics` strings sit inside the admin blocks.) At the same time, what an agent actually needs is missing. There is no per-directory or per-crate map. `entry_points` is 20 `lib.rs`/`main.rs` paths with no description, and `top_referenced_symbols` lists `join` and `open`. In a 1,500-file repository the agent still has to call `repo_map` to learn its layout. `package_duplicate_ids` also lists every shadowed digest (5 for svelte, 4 for several others). That is useful to an operator and noise to an agent. ## Proposal - The default reply is the **orientation core**: languages and counts, a per-top-level-directory summary (files, symbols, the 3 most-referenced symbols in each), entry points, and index state. - Operator health goes behind `detail: "health"` (or the existing `code-index://project/overview` resource): plugin activation, package updates, duplicate ids, `file_health`, `count_basis`. - `semantics` strings appear once per reply in a `glossary` link, not inside every block. ## Acceptance - The default reply is at most 2.5k tokens on this repository. - The health detail keeps every field it has today, and the disclosure registries stay green. Found by the automated agent-usefulness review (2026-11-09). I reproduced the size in the main session, where the reply was larger still because of the linked worktrees. --- _Filed from a five-agent review of master @ e3ec6ead (bloat, robustness, agent usefulness, docs, architecture). Every finding was spot-checked in the main session before filing._

buildagent added the

labels

2026-11-09 08:03:47 +01:00

buildagent referenced this issue

2026-11-09 08:35:50 +01:00

resolution_by_kind is distorted by construction: receiver heads emitted as type, member_access 100% circular, local rows in denominators #549

buildagent commented

2026-11-09 08:36:24 +01:00

Author

Member

Per-language sizes (2026-11-09, corpus copies, envelope default):

Repo	Overview size	Orientation share	Largest block
python-flask	19.5 KB	12.7%	`file_health` 8 KB
php-guzzle	18 KB	~10%	`file_health` 46%
ruby-sinatra	18.8 KB	~9%	admin + `file_health` ~15 KB
cs-dapper	20 KB	~4%	`file_health` 41%
ts-zod	22 KB	13.5%	`file_health` 9.4 KB
js-express	4.7k tokens	~10%	`file_health` 41%
rust-ripgrep	19.5 KB	—	`file_health` + admin 43%
13-file framework fixture	3.2k tokens	~400 tokens	—

Also:

top_referenced_symbols is noise in several languages: all require aliases in JS; a test helper (connection, 607) ahead of the Dapper API in C#.
resolution_gaps ships summary and by_kind as identical copies.
There is no per-package map for monorepos (zod).

#549 covers the metric distortions.

Per-language sizes (2026-11-09, corpus copies, `envelope` default): | Repo | Overview size | Orientation share | Largest block | |---|---|---|---| | python-flask | 19.5 KB | 12.7% | `file_health` 8 KB | | php-guzzle | 18 KB | ~10% | `file_health` 46% | | ruby-sinatra | 18.8 KB | ~9% | admin + `file_health` ~15 KB | | cs-dapper | 20 KB | ~4% | `file_health` 41% | | ts-zod | 22 KB | 13.5% | `file_health` 9.4 KB | | js-express | 4.7k tokens | ~10% | `file_health` 41% | | rust-ripgrep | 19.5 KB | — | `file_health` + admin 43% | | 13-file framework fixture | 3.2k tokens | ~400 tokens | — | Also: - `top_referenced_symbols` is noise in several languages: all `require` aliases in JS; a test helper (`connection`, 607) ahead of the Dapper API in C#. - `resolution_gaps` ships `summary` and `by_kind` as identical copies. - There is no per-package map for monorepos (zod). #549 covers the metric distortions.

~~buildagent referenced this issue 2026-11-09 09:21:00 +01:00~~

Tool discovery and replies cost extra calls, while review and navigation still have gaps #521

buildagent commented

2026-11-09 09:21:40 +01:00

Author

Member

Consolidated into #521 during the 2026-11-09 triage. The remaining scope of this issue is tracked there as a checklist item; this report stays as the detailed evidence.

Consolidated into **#521** during the 2026-11-09 triage. The remaining scope of this issue is tracked there as a checklist item; this report stays as the detailed evidence.

buildagent closed this issue

2026-11-09 09:21:40 +01:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

h-dv/code-index#522

No description provided.

Rows
Columns