Progressive Code Understanding Pipeline with Scalable LLM Depth

[ja-kjub]

I’d like to propose an improvement to codebase understanding tools that currently rely on a mostly binary model: either a lightweight structural scan or a full expensive LLM-driven analysis.

Instead, the system should be designed as a progressive pipeline with explicit control over semantic depth and token usage.

⸻

Current model (problem):
PASS 1 → structural scan (AST / filesystem)
PASS 2 → LLM enrichment (expensive, usually all-or-nothing)
PASS 3 → graph + HTML dashboard

This creates inefficiency for large repositories because users are forced to either:

• stay at low-information structural level, or
• pay full cost for deep understanding even when unnecessary

⸻

Proposed model: Progressive Understanding Pipeline

PASS 1 → Structural Indexing (always ON, deterministic)

• filesystem tree
• AST symbols (functions, classes, exports)
• import/dependency graph
• optional header-only mode for large repos

PASS 2 → Semantic Enrichment (scalable, NOT binary)
Introduce a depth parameter instead of ON/OFF:

• /deepen 10% → file-level graph only, 1-line descriptions
• /deepen 30% → module-level grouping, light LLM sampling
• /deepen 60% → architecture-level reasoning, selective full file analysis
• /deepen 100% → full semantic enrichment (current “/understand” level)

Key improvement: PASS 2 becomes incremental and budget-controlled instead of global.

Additional optimizations:

• sampling-based LLM calls (not all files)
• importance-weighted analysis (central files first)
• incremental reprocessing of changed files only
• header-first fallback for large repositories

PASS 3 → Graph + HTML Dashboard (deterministic)

• always rendered from structured graph data
• no dependency on LLM output quality
• supports progressive refinement as PASS 2 deepens

⸻

Key idea:
The system becomes a progressive resolution model rather than a binary understanding model. Users can explore the same codebase at different semantic depths without wasting tokens on unnecessary full analysis runs.

This enables:

• fast scaffolding of large repositories (10–30% depth)
• interactive exploration via graph UI
• controlled cost scaling during development
• full-depth analysis only when needed (100%)

⸻

In practice, this would allow workflows like:

• /scan → instant structure view
• /graph → lightweight visualization
• /deepen 30% → usable architecture overview
• /deepen 100% → production-level understanding

This turns codebase understanding into a continuously scalable system rather than a one-shot expensive operation.