[workflow-style] Normalize report formatting for copilot-pr-merged-report

[github-actions]

Workflow to Update

Workflow File: .github/workflows/copilot-pr-merged-report.md

Issue: This workflow generates daily reports analyzing Copilot pull requests but doesn't include markdown style guidelines for formatting the reports it creates via create-discussion.

Required Changes

Update the workflow prompt to include formatting guidelines by importing the shared reporting guidelines. The workflow already imports shared/reporting.md, but this import should be referenced explicitly in the workflow instructions.

Option 1: Add Reference to Shared Import (Recommended)

Add a section referencing the imported guidelines:

## Report Formatting

**Follow the formatting guidelines from `shared/reporting.md`**, which include:
- Use h3 (###) or lower for all headers
- Wrap long sections in `<details>` tags for progressive disclosure
- Keep critical information visible (summary, key metrics, recommendations)
- Follow design principles: trust through clarity, exceed expectations, create delight, maintain consistency

Option 2: Inline Guidelines (Alternative)

If a more explicit reminder is needed, add the full formatting section:

## 📝 Report Formatting Guidelines

**CRITICAL**: Follow these formatting guidelines to create well-structured, readable reports:

### 1. Header Levels
**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**

The discussion title serves as h1, so all content headers should start at h3:
- Use `###` for main sections (e.g., "### PR Summary", "### Token Analysis")
- Use `####` for subsections (e.g., "#### Code Generation Metrics", "#### Test Coverage")
- Never use `##` (h2) or `#` (h1) in the report body

### 2. Progressive Disclosure
**Wrap long sections in `<details><summary><b>Section Name</b></summary>` tags to improve readability and reduce scrolling.**

Use collapsible sections for:
- Individual PR details and file changes
- Detailed token usage breakdowns
- Full commit logs and test results
- Verbose statistics and metrics

Example:
\`\`\`markdown
<details>
<summary><b>View Full PR Details</b></summary>

[Long PR analysis...]

</details>
\`\`\`

### 3. Report Structure Pattern

Your report should follow this structure for optimal readability:

1. **Daily Summary** (always visible): Brief overview of merged PRs, total code generated, key metrics
2. **Key Metrics and Highlights** (always visible): Token usage, test coverage, notable PRs
3. **Detailed PR Breakdown** (in `<details>` tags): Per-PR analysis, file changes, commit details
4. **Recommendations** (always visible): Actionable insights and suggestions

### Design Principles

Create reports that:
- **Build trust through clarity**: Most important info (summary, key metrics) immediately visible
- **Exceed expectations**: Add helpful context, trends, comparisons to previous days
- **Create delight**: Use progressive disclosure to reduce overwhelm for detailed data
- **Maintain consistency**: Follow the same patterns as other reporting workflows

Example Reference Workflows

See these workflows for excellent examples of structured reporting:

• daily-repo-chronicle.md - Comprehensive formatting guidelines with design principles
• weekly-issue-summary.md - Clear structure with progressive disclosure
• agent-performance-analyzer.md - Well-organized report template with collapsible sections

Benefits

Adding these guidelines will:

• ✅ Improve report readability by keeping critical info visible
• ✅ Reduce scrolling with progressive disclosure for detailed breakdowns
• ✅ Maintain consistency with other reporting workflows
• ✅ Create a better user experience following Airbnb-inspired design principles

Agent Task

Update the workflow file .github/workflows/copilot-pr-merged-report.md to include the formatting guidelines. The easiest approach is Option 1 - add a brief reference to the shared import since the file already imports shared/reporting.md.

AI generated by Workflow Normalizer

• expires on Feb 6, 2026, 12:30 PM UTC