Background
Workers testing CodeLens raised three concerns that are actually documentation/UX gaps, not bugs:
- "Visual noise in dense files" —
--format compact and --lite flags exist exactly for this, but workers didn't know to use them.
- "Performance overhead on first indexing" — expected behavior (first scan builds graph, incremental scans are cheap), but not communicated anywhere.
- "Over-reliance on reference count as importance signal" — reference count = popularity, not criticality. A function called once in the payment flow can be more critical than a utility called 50x. This distinction is not documented.
What needs to change
--help output
- Every command that produces verbose output should mention
--format compact and --lite in its help text, not just in global flags.
scan help should note: "First scan builds the graph (slower). Subsequent scans are incremental."
README / SKILL.md
- Add a "Reading the output" or "Interpreting signals" section that explicitly states:
reference_count / caller count = how often something is called, not how important it is- Use
trace --direction up to find who calls a function, then judge importance from context
- Use
--format compact for AI/script consumption, --lite for reduced output in large repos
- First
scan is intentionally slower — it builds the SQLite graph. Subsequent runs are incremental.
CONTEXT.md (worker-skills)
- Add a "How to read CodeLens output" section with the same signal-vs-metric distinction so workers don't misinterpret reference counts.
Definition of Done
codelens scan --help mentions incremental behaviorcodelens summary --help and codelens trace --help mention --format compact / --lite- README has a "Interpreting signals" section (short, ≤10 lines)
- CONTEXT.md updated with the same note
Labels
type: improvement exec: parallel
Background
Workers testing CodeLens raised three concerns that are actually documentation/UX gaps, not bugs:
--format compactand--liteflags exist exactly for this, but workers didn't know to use them.What needs to change
--helpoutput--format compactand--litein its help text, not just in global flags.scanhelp should note: "First scan builds the graph (slower). Subsequent scans are incremental."README / SKILL.md
reference_count/ caller count = how often something is called, not how important it istrace --direction upto find who calls a function, then judge importance from context--format compactfor AI/script consumption,--litefor reduced output in large reposscanis intentionally slower — it builds the SQLite graph. Subsequent runs are incremental.CONTEXT.md (worker-skills)
Definition of Done
codelens scan --helpmentions incremental behaviorcodelens summary --helpandcodelens trace --helpmention--format compact/--liteLabels
type: improvementexec: parallel