[workflow-style] Normalize report formatting for cli-consistency-checker

[github-actions]

Workflow File: .github/workflows/cli-consistency-checker.md

This workflow checks CLI consistency and generates reports but doesn't include markdown style guidelines, which can lead to inconsistent formatting and poor readability.

Required Changes

Update the workflow prompt to include these formatting guidelines:

1. Header Levels

Add instruction: "Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy."

The report title serves as h1, so all content headers should start at h3:

• Use ### for main sections (e.g., "### Consistency Check Summary", "### Issues Found")
• Use #### for subsections (e.g., "#### Naming Violations", "#### Flag Inconsistencies")
• Never use ## (h2) or # (h1) in the report body

2. Progressive Disclosure

Add instruction: "Wrap long sections in <details><summary><b>Section Name</b></summary> tags to improve readability and reduce scrolling."

Use collapsible sections for:

• Detailed violation lists
• Per-command analysis
• Full comparison tables
• Complete code snippets

Example:

<details>
<summary><b>View All Detected Violations</b></summary>

[Complete list of CLI consistency issues...]

</details>

3. Report Structure

Suggest a structure like:

1. Brief summary (always visible): Total commands checked, violations found
2. Key issues (always visible): Most critical inconsistencies requiring attention
3. Detailed violation analysis (in <details> tags): Per-command breakdowns, code references
4. Recommendations (always visible): Actionable steps to improve CLI consistency

Design Principles (Airbnb-Inspired)

The updated workflow should create reports that:

1. Build trust through clarity: Most important consistency issues immediately visible
2. Exceed expectations: Add context like best practices, fix suggestions, impact analysis
3. Create delight: Use progressive disclosure to make detailed analysis accessible but not overwhelming
4. Maintain consistency: Follow the same patterns as other reporting workflows (meta!)

Example Reference

See workflows like audit-workflows.md or daily-repo-chronicle.md for good examples of structured reporting.

Agent Task

Update the workflow file .github/workflows/cli-consistency-checker.md to include the formatting guidelines above. Test to ensure well-formatted reports.

AI generated by Workflow Normalizer

• expires on Feb 9, 2026, 12:31 PM UTC