The progressive-depth help engine that discovers features, generates depth-layered templates, and serves contextual help
Failure modes
| Symptom | Cause | Fix | Severity |
|---|---|---|---|
TypeError: 'list' object is not callable on report.stale_features() |
stale_features is a property, not a method |
Drop the () — report.stale_features |
high |
populate() returns None |
Template ID not found in the generated directory | Confirm the ID and generated_dir; generate first |
medium |
| Stale content served after source changed | Templates not regenerated | Run run_maintenance(..., dry_run=False) |
medium |
| Cross-links resolve to the wrong/old target | Stale cross-link cache | invalidate_cross_links_cache() and retry |
low |
| Progressive depth never advances | Session state keyed to a different topic | Check help.session state; reset_session() to clear |
low |
Risk areas
- Properties vs methods.
StalenessReportandMaintenanceResultexpose counts as properties — calling them raisesTypeError. populatecan returnNone. It isPopulatedTemplate | None— guard the result before using it.- Scope confusion. The engine is
src/attune/help/; the doc authoring tooling and the ops help tab are separate surfaces.
Diagnosis order
- Confirm the manifest loads:
load_manifest(".help"). - Confirm the template exists:
populate("<id>")is notNone. - Rule out staleness:
check_staleness(...).stale_features. - For cross-link issues:
invalidate_cross_links_cache(). - For progressive depth: inspect
help.sessionstate.