# Config-Audit UX Rules

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

## Output Rules

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

## Narration Rules

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

## Formatting Rules

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

## Command Format

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