[workflow-style] Normalize report formatting across daily/weekly reporting workflows

[github-actions]

Executive Summary

Audit Date: 2026-02-07
Workflows Reviewed: 206 total workflows
Compliance Status:

• ✅ 26 workflows (13%) follow comprehensive formatting guidelines
• ⚠️ 97+ workflows (47%) create reports but lack structured formatting guidelines
• 🔹 83 workflows (40%) don't create reports (not applicable)

Problem Statement

Many agentic workflows generate reports (via create-issue, create-discussion, add-comment) but lack consistent markdown formatting guidelines. This creates:

• Inconsistent user experience across workflow reports
• Readability issues with long, unstructured content
• Missed opportunities for progressive disclosure patterns
• Information overload when reports don't use collapsible sections

Best Practice Examples

Workflows like daily-repo-chronicle, audit-workflows, daily-firewall-report, and daily-issues-report demonstrate excellent formatting with:

✅ Proper header hierarchy - Use h3 (###) or lower in report body
✅ Progressive disclosure - Long content wrapped in <details> tags
✅ Clear structure - Summary visible, details collapsible
✅ Design principles - Following Airbnb-inspired UX patterns

Recommended Standards

All reporting workflows should include these guidelines in their prompts:

1. Header Levels

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

The discussion/issue title serves as h1, so content headers must start at h3.

2. Progressive Disclosure

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

Example structure:

### Summary
[Brief overview - always visible]

### Key Metrics
[Critical stats - always visible]

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

[Long detailed content here...]

</details>

### Recommendations
[Actionable items - always visible]

3. Report Structure

Suggest a consistent pattern:

• Brief summary (always visible): 1-2 paragraphs of key findings
• Key metrics/highlights (always visible): Critical information
• Detailed analysis (in <details> tags): Per-item breakdowns, logs, verbose data
• Recommendations (always visible): Actionable next steps

Design Principles (Airbnb-Inspired)

Reports should create delightful user experiences by:

1. Building trust through clarity: Most important info immediately visible
2. Exceeding expectations: Add helpful context, trends, comparisons
3. Creating delight: Use progressive disclosure to reduce overwhelm
4. Maintaining consistency: Follow patterns across all reporting workflows

High-Priority Workflows

The following workflows generate frequent reports and should be updated first:

Daily Reporting Workflows (13 workflows):

• daily-cli-performance
• daily-code-metrics
• daily-copilot-token-report
• daily-mcp-concurrency-analysis
• daily-multi-device-docs-tester
• daily-observability-report
• daily-performance-summary
• daily-safe-output-optimizer
• daily-secrets-analysis
• daily-syntax-error-quality
• daily-team-evolution-insights
• daily-team-status
• daily-testify-uber-super-expert

Weekly Reporting Workflows (1 workflow):

• weekly-issue-summary

Other High-Impact Workflows (5 workflows):

• copilot-pr-merged-report
• copilot-pr-nlp-analysis
• copilot-pr-prompt-analysis
• copilot-session-insights
• commit-changes-analyzer

Implementation Plan

Phase 1: Update daily/weekly reporting workflows (19 workflows)
Phase 2: Update other high-frequency workflows (25 workflows)
Phase 3: Update remaining reporting workflows as needed (50+ workflows)

Reference Workflows

Use these as examples when updating workflows:

• .github/workflows/daily-repo-chronicle.md - Excellent progressive disclosure
• .github/workflows/audit-workflows.md - Clean structure with collapsible details
• .github/workflows/daily-firewall-report.md - Comprehensive formatting section

Success Criteria

A workflow is compliant when it includes:

• Explicit instruction to use h3 (###) or lower for headers
• Guidance on using <details> tags for long content
• Suggested report structure pattern
• Reference to design principles (clarity, delight, consistency)

Next Steps

1. Review and approve this normalization plan
2. Create targeted issues for Phase 1 workflows (daily/weekly)
3. Update workflow prompts with formatting guidelines
4. Monitor next runs to verify improved report formatting
5. Proceed with Phase 2 and Phase 3 as capacity allows

AI generated by Workflow Normalizer

• expires on Feb 8, 2026, 3:21 AM UTC

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster