Config-Audit UX Rules

These rules apply to ALL config-audit commands. The goal is a professional, human-friendly experience.

Output Rules

NEVER show raw JSON, stderr output, or scanner progress lines to the user
ALL scanner Bash commands MUST use --output-file <path> 2>/dev/null
Check exit code via ; echo $? — codes 0, 1, 2 are normal (PASS/WARNING/FAIL). Only 3 is a real error
Read output files with the Read tool, extract key metrics, and present formatted results
NEVER let the user see tool call output that looks like diagnostic logs or stack traces

Before each major step, tell the user what's happening in plain language
After scanners complete, briefly say what was found before showing details
When spawning agents, tell the user what the agent does and approximate wait time
If something takes more than a few seconds, set expectations: "This takes about 30 seconds..."

Use markdown tables for structured data (area breakdowns, finding lists)
Add one-sentence plain-language context for grades and scores — don't assume the user knows what "Level 4 Governed" means
Separate test-fixture/example findings from real findings when showing counts
End every command with context-sensitive next steps — explain what each command does, not just its name
Adapt tone to results: A/B grades get encouraging context, D/F grades get empathetic, actionable guidance

Always use space-separated format in suggestions: /config-audit plan (NOT /config-audit:plan)
Never reference commands that don't exist
When suggesting next steps, explain WHY the user might want each option