Normalize report formatting guidelines across Phase 1 workflows by Copilot · Pull Request #14311 · github/gh-aw

Copilot · 2026-02-07T08:08:08Z

Many agentic workflows generate reports without structured formatting guidelines, creating inconsistent UX and readability issues. Phase 1 addresses 19 daily/weekly reporting workflows.

Changes

Added comprehensive formatting guidelines to 12 workflows:

Daily workflows: daily-mcp-concurrency-analysis, daily-multi-device-docs-tester, daily-safe-output-optimizer, daily-secrets-analysis, daily-syntax-error-quality, daily-team-evolution-insights, daily-testify-uber-super-expert
High-impact workflows: copilot-pr-merged-report, copilot-pr-nlp-analysis, copilot-pr-prompt-analysis, copilot-session-insights, commit-changes-analyzer

7 workflows already compliant (no changes needed): daily-cli-performance, daily-code-metrics, daily-copilot-token-report, daily-observability-report, daily-performance-summary, daily-team-status, weekly-issue-summary

Guidelines Template

Each workflow now includes standardized section before output requirements:

## 📝 Report Formatting Guidelines

### 1. Header Levels
Use h3 (###) or lower for all content headers. Discussion/issue title is h1.

### 2. Progressive Disclosure
Wrap long sections in `<details><summary><b>Section Name</b></summary>` tags.

### 3. Report Structure Pattern
1. Brief Summary (visible)
2. Key Metrics (visible)
3. Detailed Analysis (<details>)
4. Recommendations (visible)

### Design Principles
- Clarity: Critical info immediately visible
- Progressive disclosure: Reduce overwhelm
- Consistency: Follow patterns across workflows

Impact

Consistent header hierarchy across all Phase 1 reports
Progressive disclosure reduces information overload
Clear template for Phase 2/3 workflow updates (78 remaining)

Original prompt

This section details on the original issue you should resolve

<issue_title>[workflow-style] Normalize report formatting across daily/weekly reporting workflows</issue_title>
<issue_description>### 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:

Building trust through clarity: Most important info immediately visible
Exceeding expectations: Add helpful context, trends, comparisons
Creating delight: Use progressive disclosure to reduce overwhelm
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

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

AI generated by [Workflow Normalizer](https://githu...

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

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

- Added standardized "Report Formatting Guidelines" section to 12 workflows - Guidelines include: header levels (h3+), progressive disclosure (<details> tags), report structure pattern, and design principles - Updated workflows: daily-mcp-concurrency-analysis, daily-multi-device-docs-tester, daily-safe-output-optimizer, daily-secrets-analysis, daily-syntax-error-quality, daily-team-evolution-insights, daily-testify-uber-super-expert, copilot-pr-merged-report, copilot-pr-nlp-analysis, copilot-pr-prompt-analysis, copilot-session-insights, commit-changes-analyzer - Recompiled all 147 workflows successfully Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

github-actions · 2026-02-07T12:19:22Z

🔍 PR Triage Results

Category: chore | Risk: low | Priority: 53/100

Scores Breakdown

Impact: 30/50 - Improves UX consistency across 12 reporting workflows by adding comprehensive formatting guidelines. Affects user experience for all workflow-generated reports. Broad reach across the codebase.
Urgency: 7/30 - Quality improvement (4.1 hours old), not urgent. Extensive changes across 12 files. Draft status. CI unstable.
Quality: 16/20 - Comprehensive changes with clear rationale. Good documentation of formatting standards. Draft status appropriate for multi-file changes.

📋 Recommended Action: batch_review

This workflow consistency improvement should be reviewed together with PRs #14302 and #14296 as part of the workflow configuration batch (batch-workflow-improvements-001). Coordinating the review ensures consistent formatting patterns across all workflow changes.

Batch Context: Review with other workflow improvements to maintain consistency and identify any conflicting changes.

Triaged by PR Triage Agent on 2026-02-07

AI generated by PR Triage Agent

Copilot

Pull request overview

This PR standardizes report formatting instructions across Phase 1 daily/weekly reporting workflows by adding a consistent “Report Formatting Guidelines” section intended to enforce header hierarchy, progressive disclosure via <details>, and a consistent report structure.

Changes:

Added a standardized “📝 Report Formatting Guidelines” block to 12 reporting workflows.
Updated an existing formatting section in daily-team-evolution-insights to match the standardized template.
Replaced a brief “follow shared/reporting.md” reminder with the full inline guidelines in daily-multi-device-docs-tester.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
.github/workflows/daily-testify-uber-super-expert.md	Adds standardized report formatting guidelines before issue generation instructions.
.github/workflows/daily-team-evolution-insights.md	Replaces prior formatting section with standardized guidelines.
.github/workflows/daily-syntax-error-quality.md	Adds standardized formatting guidelines before issue creation phase.
.github/workflows/daily-secrets-analysis.md	Adds standardized formatting guidelines before discussion report instructions.
.github/workflows/daily-safe-output-optimizer.md	Adds standardized formatting guidelines before output requirements.
.github/workflows/daily-multi-device-docs-tester.md	Replaces shared/reporting.md pointer with inline standardized guidelines.
.github/workflows/daily-mcp-concurrency-analysis.md	Adds standardized formatting guidelines before output requirements.
.github/workflows/copilot-session-insights.md	Adds standardized formatting guidelines before discussion creation phase.
.github/workflows/copilot-pr-prompt-analysis.md	Adds standardized formatting guidelines before discussion creation phase.
.github/workflows/copilot-pr-nlp-analysis.md	Adds standardized formatting guidelines before discussion creation phase.
.github/workflows/copilot-pr-merged-report.md	Adds standardized formatting guidelines before report generation instructions.
.github/workflows/commit-changes-analyzer.md	Adds standardized formatting guidelines before developer report section.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-07T13:21:49Z

.github/workflows/copilot-session-insights.md

+**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**
+
+The issue or discussion title serves as h1, so all content headers should start at h3:
+- Use `###` for main sections (e.g., "### Executive Summary", "### Key Metrics")
+- Use `####` for subsections (e.g., "#### Detailed Analysis", "#### Recommendations")


The new formatting guidelines require the discussion title to be the only h1 and forbid ## in the report body, but the provided discussion template still starts with # 🤖 ... and then uses ## Executive Summary, ## Key Metrics, etc. Align the template with the guideline by removing the body-level # title and changing all ## headings to ### (and deeper levels to ####).

Copilot · 2026-02-07T13:21:49Z

.github/workflows/copilot-pr-prompt-analysis.md

+**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**
+
+The issue or discussion title serves as h1, so all content headers should start at h3:
+- Use `###` for main sections (e.g., "### Executive Summary", "### Key Metrics")
+- Use `####` for subsections (e.g., "#### Detailed Analysis", "#### Recommendations")


This adds header-level guidelines (no #/## in the discussion body), but the discussion template that follows still uses an h1 (# 🤖 ...) and h2 sections (## Summary, etc.). Update the template to start at ### and use #### for subsections so it is consistent with the new guideline and shared/reporting.md.

Copilot · 2026-02-07T13:21:49Z

.github/workflows/copilot-pr-nlp-analysis.md

+### 1. Header Levels
+**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**
+
+The issue or discussion title serves as h1, so all content headers should start at h3:
+- Use `###` for main sections (e.g., "### Executive Summary", "### Key Metrics")


The guidelines added here say the report body must not use #/##, but the content template below still begins with # 🤖 ... and uses ## Executive Summary, etc. Please adjust the template to comply (remove the body-level h1 and replace h2s with h3s / h4s).

Copilot · 2026-02-07T13:21:49Z

.github/workflows/copilot-pr-merged-report.md

+### 1. Header Levels
+**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**
+
+The issue or discussion title serves as h1, so all content headers should start at h3:
+- Use `###` for main sections (e.g., "### Executive Summary", "### Key Metrics")


The inserted guidelines forbid #/## headings in the report body, but the report template below still uses # 🤖 ... and multiple ## sections (Summary, Merged Pull Requests, etc.). This is inconsistent with both the new guidance and shared/reporting.md; update the template to use ###/#### headings only and rely on the issue/discussion title for h1.

Copilot · 2026-02-07T13:21:50Z

.github/workflows/daily-testify-uber-super-expert.md

+**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**
+
+The issue or discussion title serves as h1, so all content headers should start at h3:
+- Use `###` for main sections (e.g., "### Executive Summary", "### Key Metrics")
+- Use `####` for subsections (e.g., "#### Detailed Analysis", "#### Recommendations")


The newly added formatting guidelines say the issue/discussion title is the only h1 and the report body should not use #/##, but the example issue template immediately below still starts with # Improve Test Quality: ... and uses multiple ## sections (e.g., "## Overview"). This is contradictory and will likely cause agents to follow the template rather than the guideline. Update the template headings to start at ### (and #### for subsections) and remove the body-level # title entirely (the issue title field already supplies the h1).

Copilot · 2026-02-07T13:21:50Z

.github/workflows/daily-team-evolution-insights.md

 **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., "### Key Observations", "### Development Patterns")
- Use `####` for subsections (e.g., "#### Team Dynamics", "#### Innovation & Learning")
+The issue or discussion title serves as h1, so all content headers should start at h3:
+- Use `###` for main sections (e.g., "### Executive Summary", "### Key Metrics")
+- Use `####` for subsections (e.g., "#### Detailed Analysis", "#### Recommendations")


This workflow now instructs that the discussion/issue title serves as h1 and the report body should not use #/##, but the discussion body template later in the file still begins with a # 🌱 Daily Team Evolution Insights - [DATE] heading. Remove that body-level h1 and start the template at ### (or plain text) so it complies with the guideline (and with shared/reporting.md).

Copilot · 2026-02-07T13:21:50Z

.github/workflows/daily-secrets-analysis.md

+**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**
+
+The issue or discussion title serves as h1, so all content headers should start at h3:
+- Use `###` for main sections (e.g., "### Executive Summary", "### Key Metrics")
+- Use `####` for subsections (e.g., "#### Detailed Analysis", "#### Recommendations")


The added guidelines prohibit #/## in the report body, but the discussion template below still uses an h1 (# 🔐 Daily Secrets Analysis Report) and multiple h2s (## 📊 Executive Summary, etc.). This undermines the normalization goal and conflicts with shared/reporting.md. Please update the template headings to use ###/#### only (and rely on the discussion title for the h1).

Initial plan

5a67375

Copilot AI assigned Copilot and pelikhan Feb 7, 2026

Copilot started work on behalf of pelikhan February 7, 2026 08:08 View session

Copilot AI changed the title ~~[WIP] Normalize report formatting across daily and weekly workflows~~ Normalize report formatting guidelines across Phase 1 workflows Feb 7, 2026

Copilot AI requested a review from pelikhan February 7, 2026 08:21

Copilot finished work on behalf of pelikhan February 7, 2026 08:21

github-actions bot mentioned this pull request Feb 7, 2026

[PR Triage Report] PR Triage Report - February 7, 2026 #14326

Closed

github-actions bot added pr-action:batch-review pr-priority:medium pr-risk:low pr-type:chore pr-batch:batch-workflow-improvements-001 labels Feb 7, 2026

pelikhan marked this pull request as ready for review February 7, 2026 13:18

Copilot AI review requested due to automatic review settings February 7, 2026 13:18

pelikhan merged commit 37ef2ed into main Feb 7, 2026
1 check passed

pelikhan deleted the copilot/normalize-report-formatting-again branch February 7, 2026 13:18

Copilot started reviewing on behalf of pelikhan February 7, 2026 13:18 View session

Copilot AI reviewed Feb 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Normalize report formatting guidelines across Phase 1 workflows#14311

Normalize report formatting guidelines across Phase 1 workflows#14311
pelikhan merged 2 commits intomainfrom
copilot/normalize-report-formatting-again

Copilot AI commented Feb 7, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Feb 7, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Copilot AI Feb 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Guidelines Template

Impact

Problem Statement

Best Practice Examples

Recommended Standards

1. Header Levels

2. Progressive Disclosure

3. Report Structure

Design Principles (Airbnb-Inspired)

High-Priority Workflows

Implementation Plan

Reference Workflows

Success Criteria

Next Steps

Uh oh!

github-actions bot commented Feb 7, 2026

🔍 PR Triage Results

Scores Breakdown

📋 Recommended Action: batch_review

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 7, 2026 •

edited

Loading