Overview

Multiple reporting workflows lack proper markdown formatting guidelines. This creates inconsistent report formatting across the repository.

Affected Workflows

🔴 Non-Compliant (No formatting guidelines)

These workflows create reports but have no formatting instructions:

1. smoke-claude.md - Creates test result issues
2. smoke-codex.md - Creates test result issues
3. smoke-copilot.md - Creates test result issues
4. poem-bot.md - Creates discussion posts

Recommendation: These workflows should import shared/reporting.md:

imports:
  - shared/reporting.md

⚠️ Partial Compliance (Missing progressive disclosure)

These workflows mention h3 headers but don't explain <details> tags (showing top 10):

1. agent-performance-analyzer.md - Creates performance analysis discussions
2. auto-triage-issues.md - Creates triage reports
3. breaking-change-checker.md - Creates breaking change issues
4. ci-doctor.md - Creates CI health reports
5. cli-consistency-checker.md - Creates consistency reports
6. cli-version-checker.md - Creates version check issues
7. copilot-cli-deep-research.md - Creates research discussions
8. craft.md - Creates workflow generation summaries
9. duplicate-code-detector.md - Creates code quality issues
10. docs-noob-tester.md - Creates documentation test reports

... and 14 more (see analysis in comments)

Recommendation: Add a "Formatting Guidelines" section explaining progressive disclosure.

Required Formatting Standards

All reporting workflows should follow these standards from shared/reporting.md:

1. Header Levels

Rule: Use h3 (###) or lower for all headers in reports to maintain proper document hierarchy.

Rationale: The issue/discussion title is already h1, and system UI may add h2 elements.

2. Progressive Disclosure

Rule: Use <details><summary><b>Section Name</b></summary> tags for long content.

Example:

### Summary
[2-3 paragraphs with key findings - always visible]

<details>
<summary><b>View Full Analysis</b></summary>

[Detailed analysis, long lists, raw data]

</details>

When to use:

• Lists with 10+ items
• Detailed technical breakdowns
• Per-file or per-author statistics
• Historical data or trends
• Raw logs or test output

3. Report Structure

Follow this pattern (inspired by Airbnb's design principles):

1. Brief summary (2-3 paragraphs) - always visible
2. Key metrics/highlights - always visible
3. Detailed analysis - in <details> tags
4. Recommendations - always visible

Implementation Options

Option 1: Import Shared Guidelines (Recommended)

Add to workflow frontmatter:

imports:
  - shared/reporting.md

Advantages:

• Consistent standards across all workflows
• Single source of truth
• Automatic updates when standards evolve

Option 2: Inline Guidelines

Add a "Report Formatting" section to the workflow with:

• Header level instructions (h3 or lower)
• Progressive disclosure examples
• Report structure template

Use when: Workflow has unique reporting needs

Benefits of Standardization

User Experience:

• ✅ Easier to scan reports for important information
• ✅ Reduced scrolling and cognitive load
• ✅ Consistent experience across all workflows
• ✅ Better mobile readability

Technical Benefits:

• ✅ Easier to maintain workflows
• ✅ Clearer expectations for AI agents
• ✅ Better integration with GitHub UI
• ✅ Improved accessibility

Design Principles (Airbnb-Inspired)

Trust Through Clarity: Important information visible upfront
Exceeding Expectations: Add helpful context and trends
Creating Delight: Use progressive disclosure to reduce overwhelm
Consistency: Same patterns across all reports

Next Steps

Phase 1: Fix non-compliant workflows (4 workflows)

• Add shared/reporting.md import
• Test report formatting

Phase 2: Improve partial compliance (24 workflows)

• Add progressive disclosure guidelines
• Update report templates
• Show before/after examples

Phase 3: Monitor compliance

• Add to workflow creation checklist
• Update documentation
• Create linting rules (future)

Reference Examples

Excellent formatting:

• daily-repo-chronicle.md - Newspaper style with progressive disclosure
• audit-workflows.md - Comprehensive audit with collapsed details
• static-analysis-report.md - Security findings with detailed views

Related Issues

• #aw_multi_device_001 - Normalize formatting for daily-multi-device-docs-tester
• #aw_team_evolution_002 - Add progressive disclosure to daily-team-evolution-insights

Success Criteria

A workflow has proper formatting guidelines when:

• ✅ It imports shared/reporting.md, OR
• ✅ It includes inline instructions for h3 headers AND progressive disclosure
• ✅ Report template shows example structure
• ✅ Guidelines explain when to use <details> tags

AI generated by Workflow Normalizer

• expires on Jan 27, 2026, 12:26 PM UTC