feat(generation): FAQ-weighted docs budget tilts depth toward asked-about modules

[RaghavChamadiya]

What

Documentation depth is chosen by graph centrality alone, blind to what developers actually ask about. This weights it by real usage: modules people query get documented deeper, cold ones get the lean treatment, at no change to the total budget.

How

• Demand aggregator (core/sessions/miners/demand.py): a read-only, local sweep of the session transcript stream that mines get_answer citations and search_codebase hits into per-file question counts. No network, no LLM.
• Per-module reallocation (selection/budget.py::allocate_module_file_pages): the planner rolls per-file demand up to its own wiki-page module granularity and redistributes the file_page budget across modules by demand.

Guarantees:

• Total conserved — reallocation, not inflation. The number of pages is unchanged.
• Floor — every module keeps a lean baseline; a well-covered but never-asked-about module leans down toward the floor to fund high-demand modules, never below it.
• Deterministic and inspectable — a page_selection.demand_tilt log prints per-module demand, baseline vs. allocated pages, and candidates so a human can audit the reallocation.
• Zero-data passthrough — with no session history the selection is byte-for-byte identical to before, so existing repos and fresh installs are unaffected.

Wiring

Added at the single selection path both full generation and incremental update funnel through, so both honor it. The cost estimator stays demand-free, so its estimate never drifts (counts are conserved). Kill switch generation.faq_weighting (default on). A one-line summary surfaces on init and update when usage shaped the run, and stays silent otherwise.

Tests

• Aggregator: module attribution, empty store, single-module skew, per-call dedup/cap, scoping, summary line.
• Allocator: floor guarantee, budget conservation, zero-data passthrough, determinism, spill-back, audit rows.
• Full generation, sessions, pipeline, and update-command suites pass; no regressions.

[repowise-bot]

✅ Health: 7.6 (unchanged)

📋 At a glance
1 file changed health · 5 hotspots touched · 8 new findings introduced · 5 co-change pairs left out · 2 files with recent fix history · 1 dead-code finding. Scoped to packages.

🚨 Change risk: high _{(riskier than 76% of this repo's commits · raw 9.5/10)}
This change's risk is driven by:

• more lines added than baseline
• more scattered than baseline

🩹 Review priority _{(files here with the most recent bug-fix history — defects cluster, so review these first)}

• .../update_cmd/command.py — fixed 4× in the last ~6 months
• .../selection/budget.py — fixed once in the last ~6 months

File	Score	Δ	Why
.../selection/budget.py	9.7 → 7.1	▼ -2.6	🔻 introduced nested complexity, complex method, large method

💡 .../selection/budget.py: Flatten the control flow. Pull early-return guards to the top, extract the deepest branch into a helper, and consider replacing nested conditionals with a strategy table or dispatch dict.

🔎 More signals (3)

🔥 Hotspots touched (5)

• .../selection/budget.py — 2 commits/90d, 3 dependents · primary owner: Raghav Chamadiya (100%)
• .../update_cmd/command.py — 14 commits/90d, 3 dependents · primary owner: Raghav Chamadiya (90%)
• .../selection/selector.py — 4 commits/90d, 3 dependents · primary owner: Raghav Chamadiya (82%)

2 more

• .../page_generator/core.py — 9 commits/90d, 4 dependents · primary owner: Raghav Chamadiya (83%)
• .../phases/generation.py — 5 commits/90d, 1 dependents · primary owner: Swati Ahuja (94%)

🔗 Hidden coupling (2 files)

• .../update_cmd/command.py co-changes with these files (not in this PR):
  • docs/CLI_REFERENCE.md (6× — 🟢 routine)
  • .../update_cmd/persistence.py (6× — 🟢 routine)
  • .../cli/helpers.py (4× — 🟢 routine)
• .../page_generator/core.py co-changes with these files (not in this PR):
  • .../pipeline/orchestrator.py (5× — 🟢 routine)
  • .../generation/models.py (4× — 🟢 routine)

💀 Dead code (1 finding)

• 💀 .../selection/selector.py language_summary (confidence 1.00)

---

📊 Full report · ⭐ Star Repowise · 📥 Install bot · Last updated 2026-07-11 13:30 UTC
_{Silence on a single PR with [skip repowise] in the title · Per-repo toggle on repowise.dev/settings?tab=bot}