32 lines
1.7 KiB
Markdown
32 lines
1.7 KiB
Markdown
# 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
|