doc-impact

You are working on doc impact — the command that shows whether generated agent context is keeping up with the codebase, optionally interprets results via LLM, and can interactively apply recommended repairs.

Domain purpose

Audits the agent context generated by aspens against the live source tree, reports per-target health (Claude, Codex), and offers an interactive --apply flow that re-runs the right aspens doc init/sync variant to repair gaps. The LLM interpretation is a thin layer on top of deterministic metrics — the metrics are the contract.

Business rules / invariants

• Target inference: If .aspens.json is absent, targets are inferred from scan results (.claude/ → claude, .agents/ → codex). Falls back to ['claude'].
• LLM is optional and tool-less. Runs only when a CLI backend is detected. runLLM is invoked with disableTools: true; prompt must return pure JSON (bottom_line, improves, risks, next_step). Failure is caught and reported as "Analysis unavailable" — never fatal.
• Graph failure is non-fatal. If buildRepoGraph throws (or --no-graph is passed), graph is null and hub coverage is skipped/n/a.
• Hub coverage haystack is the code-map, not CLAUDE.md. Post-Phase 1, ## Key Files no longer lives in root instructions. computeHubCoverage reads .claude/code-map.md (claude) or .agents/skills/architecture/references/code-map.md (codex). If the code-map file is missing, it reports codeMapMissing: true instead of spurious "missing hub" warnings. Older callers without repoPath fall back to the legacy contextText haystack.
• Health score deductions (start 100): missing instructions −35; no skills −25; domain gaps proportional up to −25; missed hubs −4 each; drift −3 per file (cap −20); unhealthy hooks −10 (hook-capable targets only); broken save-tokens −5 (claude only).
• LOW_SIGNAL_DOMAIN_NAMES (config, test, tests, __tests__, spec, e2e) are excluded from coverage scoring but tracked in excluded.
• SOURCE_EXTS extends the scanner set with .scala, .clj, .elm, .vue, .svelte for drift detection. Adding a language for drift requires updating this set.
• Walk depth capped at 5 — deep nested source files won't appear in drift analysis.

Non-obvious behaviors

• Agent skill-ref check (Phase 6): checkAgentSkillReferences() scans .claude/agents/*.md frontmatter for skills: [a, b] and verifies each .claude/skills/<name>/skill.md exists. Broken refs surface as agent-skill-refs opportunities.
• Save-tokens health is Claude-only and only activates when config.saveTokens.enabled is true and claude.enabled !== false. Required hook/command files vary by sub-config (saveHandoff, warnAtTokens/compactAtTokens thresholds). Legacy .mjs siblings of the .sh hooks must be cleaned up — their presence is an issue.
• buildApplyPlan dedupes with aspens doc sync as a target-agnostic key; everything else is keyed ${target.id}:${action}.
• applyRecommendedAction is a hand-maintained dispatch table mapping action strings to docInitCommand/docSyncCommand option shapes. Adding a new recommendation in recommendActions() requires a matching branch here, otherwise it warns "Cannot apply automatically".

Critical files (purpose, not inventory)

• src/commands/doc-impact.js — CLI rendering, LLM prompt assembly, buildApplyPlan, and the action dispatch into docInitCommand/docSyncCommand.
• src/lib/impact.js — All deterministic analysis (analyzeImpact, target summarization, scoring, drift, hub/code-map coverage, hook/save-tokens health, opportunities, missing rollup, value comparison).
• src/prompts/impact-analyze.md — Strict JSON contract the LLM must honor; do not change shape without updating parseAnalysis.

Critical Rules

• Skills/activationPatterns are matched via findMatchingSkill (substring or /domain/ path hit). Renaming the skill-reader contract breaks coverage scoring.
• Don't surface root-context hub warnings when codeMapMissing is true — emit the code-map-missing item instead and tell the user to run aspens doc graph.
• Exported surface used by tests/consumers: computeDomainCoverage, computeHubCoverage, computeDrift, evaluateHookHealth, evaluateSaveTokensHealth, computeHealthScore, computeTargetStatus, recommendActions, summarizeReport, summarizeMissing, summarizeOpportunities, summarizeValueComparison, checkAgentSkillReferences from impact.js; buildApplyPlan, buildApplyConfirmationMessage from doc-impact.js.

Last Updated: 2026-05-11