Read-only DB health audit with interactive recommendations
Read-only health audit of the task database followed by interactive recommendations.
Phase 1 runs a non-interactive audit across 6 categories, presenting findings as a structured report. Phase 2 opens an interactive Q&A session for deeper exploration.
tusk config
Parse the JSON. Note which arrays are empty — empty means no validation is configured for that column:
domains → [] means skip domain orphan checksagents → {} means skip agent orphan checksHold onto the config values for Phase 2 (recommendations).
Run the built-in audit command to get counts for all six categories:
tusk audit
This returns JSON with config_fitness, task_hygiene, dependency_health, session_gaps, criteria_gaps, and scoring_gaps counts. All six keys are always present even when the count is zero.
For each category with a count > 0, load the companion file and run the corresponding detail queries:
Read file: <base_directory>/QUERIES.md
Present findings grouped by category with task IDs and summaries so the user can act on them. Categories with zero findings get a single line: ✓ No issues found.
Report format:
## Tusk Health Audit
### 1. Config Fitness — {N} finding(s)
... detail from QUERIES.md ...
### 2. Task Hygiene — ✓ No issues found
(skipped because count was 0)
### 3. Dependency Health — {N} finding(s)
... detail ...
(etc. for all 6 categories)
Always run this step regardless of finding counts — velocity is informational, not a health issue.
Run the Velocity query:
tusk -header -column "
SELECT week, task_count, ROUND(avg_cost, 4) as avg_cost
FROM v_velocity
ORDER BY week DESC
LIMIT 8;
"
Present results in the audit report as:
### Velocity — Tasks Completed Per Week
week task_count avg_cost
---------- ---------- --------
2025-W08 3 0.1523
2025-W07 5 0.2100
...
If the query returns no rows, display:
### Velocity — No completed tasks recorded yet
After presenting the audit report, load the Q&A templates:
Read file: <base_directory>/RECOMMENDATIONS.md
Present the user with 5 discussion topics:
Ask which topic they'd like to explore. For each chosen topic, run the corresponding queries from RECOMMENDATIONS.md, analyze the results, and provide actionable recommendations.
The user can explore multiple topics or end the session at any time.