Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(doctor): explain stale pages and why --repair cannot clear them (#1710) (#1956)

Nehal kanak kuniyil thottathilcde2480bb3cb
diff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
index c20309e40..428094368 100644
--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py
@@ -232,7 +232,19 @@ def _run_repo_checks(
return 0
stale_count = run_async(_check_stale())
- checks.append(_check("Stale pages", stale_count == 0, f"{stale_count} stale"))
+ if stale_count:
+ checks.append(
+ _check(
+ "Stale pages",
+ False,
+ f"{stale_count} stale — pages whose content lags the code "
+ "(change cascade exceeded the regeneration budget). "
+ "`repowise update --full` regenerates them; "
+ "`--repair` cannot, it only fixes store drift.",
+ )
+ )
+ else:
+ checks.append(_check("Stale pages", True, "0 stale"))
except Exception:
checks.append(_check("Stale pages", True, "Could not check"))
@@ -697,8 +709,21 @@ def _run_repo_checks(
repaired_count = run_async(_repair())
console.print(f"[bold green]Repaired {repaired_count} entries.[/bold green]")
+ if stale_count:
+ console.print(
+ "[yellow]Stale pages are not store drift, so --repair leaves them "
+ "alone: they are pages the last docs run could not regenerate "
+ "within its budget. Run `repowise update --full` to clear them.[/yellow]"
+ )
elif repair and not has_mismatches and not registration_wedged and not agents_need_refresh:
- console.print("[green]Nothing to repair.[/green]")
+ if stale_count:
+ console.print(
+ f"[yellow]No store drift to repair, but {stale_count} stale page(s) "
+ "remain — they are content lag, not drift. `repowise update --full` "
+ "regenerates them.[/yellow]"
+ )
+ else:
+ console.print("[green]Nothing to repair.[/green]")
if repair and agents_need_refresh:
from repowise.cli.commands.agents_cmd import refresh_wired_agents