Normalize report formatting guidelines across Phase 1 workflows

.github/workflows/commit-changes-analyzer.md

@@ -154,6 +154,54 @@ Use list_releases to check for releases in the timeframe
 
 ### 5. Generate Developer Report
 
+## 📝 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 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")
+- 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:
+- Detailed analysis and verbose data
+- Per-item breakdowns when there are many items
+- Complete logs, traces, or raw data
+- Secondary information and extra context
+
+Example:
+```markdown
+<details>
+<summary><b>View Detailed Analysis</b></summary>
+
+[Long detailed content here...]
+
+</details>
+```
+
+### 3. Report Structure Pattern
+
+Your report should follow this structure for optimal readability:
+
+1. **Brief Summary** (always visible): 1-2 paragraph overview of key findings
+2. **Key Metrics/Highlights** (always visible): Critical information and important statistics
+3. **Detailed Analysis** (in `<details>` tags): In-depth breakdowns, verbose data, complete lists
+4. **Recommendations** (always visible): Actionable next steps and suggestions
+
+### Design Principles
+
+Create reports that:
+- **Build trust through clarity**: Most important info immediately visible
+- **Exceed expectations**: Add helpful context, trends, comparisons
+- **Create delight**: Use progressive disclosure to reduce overwhelm
+- **Maintain consistency**: Follow the same patterns as other reporting workflows
+
 Create a comprehensive markdown report with the following sections:
 
 #### Executive Summary

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

@@ -146,6 +146,54 @@ For token usage information, we need to find the workflow run associated with th
 
 ### Phase 3: Generate Report
 
+## 📝 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 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")
+- 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:
+- Detailed analysis and verbose data
+- Per-item breakdowns when there are many items
+- Complete logs, traces, or raw data
+- Secondary information and extra context
+
+Example:
+```markdown
+<details>
+<summary><b>View Detailed Analysis</b></summary>
+
+[Long detailed content here...]
+
+</details>
+```
+
+### 3. Report Structure Pattern
+
+Your report should follow this structure for optimal readability:
+
+1. **Brief Summary** (always visible): 1-2 paragraph overview of key findings
+2. **Key Metrics/Highlights** (always visible): Critical information and important statistics
+3. **Detailed Analysis** (in `<details>` tags): In-depth breakdowns, verbose data, complete lists
+4. **Recommendations** (always visible): Actionable next steps and suggestions
+
+### Design Principles
+
+Create reports that:
+- **Build trust through clarity**: Most important info immediately visible
+- **Exceed expectations**: Add helpful context, trends, comparisons
+- **Create delight**: Use progressive disclosure to reduce overwhelm
+- **Maintain consistency**: Follow the same patterns as other reporting workflows
+
 Create a concise report with the following structure:
 
 ```markdown

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

@@ -233,6 +233,54 @@ For each generated chart:
 
 ### Phase 6: Create Analysis Discussion
 
+## 📝 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 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")
+- 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:
+- Detailed analysis and verbose data
+- Per-item breakdowns when there are many items
+- Complete logs, traces, or raw data
+- Secondary information and extra context
+
+Example:
+```markdown
+<details>
+<summary><b>View Detailed Analysis</b></summary>
+
+[Long detailed content here...]
+
+</details>
+```
+
+### 3. Report Structure Pattern
+
+Your report should follow this structure for optimal readability:
+
+1. **Brief Summary** (always visible): 1-2 paragraph overview of key findings
+2. **Key Metrics/Highlights** (always visible): Critical information and important statistics
+3. **Detailed Analysis** (in `<details>` tags): In-depth breakdowns, verbose data, complete lists
+4. **Recommendations** (always visible): Actionable next steps and suggestions
+
+### Design Principles
+
+Create reports that:
+- **Build trust through clarity**: Most important info immediately visible
+- **Exceed expectations**: Add helpful context, trends, comparisons
+- **Create delight**: Use progressive disclosure to reduce overwhelm
+- **Maintain consistency**: Follow the same patterns as other reporting workflows
+
 Post a comprehensive discussion with the following structure:
 
 **Title**: `Copilot PR Conversation NLP Analysis - [DATE]`

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

@@ -186,6 +186,54 @@ Based on the analysis, generate actionable insights:
 
 ### Phase 6: Create Analysis Discussion
 
+## 📝 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 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")
+- 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:
+- Detailed analysis and verbose data
+- Per-item breakdowns when there are many items
+- Complete logs, traces, or raw data
+- Secondary information and extra context
+
+Example:
+```markdown
+<details>
+<summary><b>View Detailed Analysis</b></summary>
+
+[Long detailed content here...]
+
+</details>
+```
+
+### 3. Report Structure Pattern
+
+Your report should follow this structure for optimal readability:
+
+1. **Brief Summary** (always visible): 1-2 paragraph overview of key findings
+2. **Key Metrics/Highlights** (always visible): Critical information and important statistics
+3. **Detailed Analysis** (in `<details>` tags): In-depth breakdowns, verbose data, complete lists
+4. **Recommendations** (always visible): Actionable next steps and suggestions
+
+### Design Principles
+
+Create reports that:
+- **Build trust through clarity**: Most important info immediately visible
+- **Exceed expectations**: Add helpful context, trends, comparisons
+- **Create delight**: Use progressive disclosure to reduce overwhelm
+- **Maintain consistency**: Follow the same patterns as other reporting workflows
+
 Create a discussion with your findings using the safe-outputs create-discussion functionality.
 
 **Discussion Title**: `Copilot PR Prompt Analysis - [DATE]`

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

@@ -123,6 +123,54 @@ Update cache memory with today's analysis following the cache management pattern
 
 ### Phase 5: Create Analysis Discussion
 
+## 📝 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 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")
+- 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:
+- Detailed analysis and verbose data
+- Per-item breakdowns when there are many items
+- Complete logs, traces, or raw data
+- Secondary information and extra context
+
+Example:
+```markdown
+<details>
+<summary><b>View Detailed Analysis</b></summary>
+
+[Long detailed content here...]
+
+</details>
+```
+
+### 3. Report Structure Pattern
+
+Your report should follow this structure for optimal readability:
+
+1. **Brief Summary** (always visible): 1-2 paragraph overview of key findings
+2. **Key Metrics/Highlights** (always visible): Critical information and important statistics
+3. **Detailed Analysis** (in `<details>` tags): In-depth breakdowns, verbose data, complete lists
+4. **Recommendations** (always visible): Actionable next steps and suggestions
+
+### Design Principles
+
+Create reports that:
+- **Build trust through clarity**: Most important info immediately visible
+- **Exceed expectations**: Add helpful context, trends, comparisons
+- **Create delight**: Use progressive disclosure to reduce overwhelm
+- **Maintain consistency**: Follow the same patterns as other reporting workflows
+
 Generate a human-readable Markdown report and create a discussion.
 
 **Discussion Title Format**:

.github/workflows/daily-mcp-concurrency-analysis.md

@@ -471,6 +471,54 @@ Example cache structure:
 }
 ```
 
+## 📝 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 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")
+- 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:
+- Detailed analysis and verbose data
+- Per-item breakdowns when there are many items
+- Complete logs, traces, or raw data
+- Secondary information and extra context
+
+Example:
+```markdown
+<details>
+<summary><b>View Detailed Analysis</b></summary>
+
+[Long detailed content here...]
+
+</details>
+```
+
+### 3. Report Structure Pattern
+
+Your report should follow this structure for optimal readability:
+
+1. **Brief Summary** (always visible): 1-2 paragraph overview of key findings
+2. **Key Metrics/Highlights** (always visible): Critical information and important statistics
+3. **Detailed Analysis** (in `<details>` tags): In-depth breakdowns, verbose data, complete lists
+4. **Recommendations** (always visible): Actionable next steps and suggestions
+
+### Design Principles
+
+Create reports that:
+- **Build trust through clarity**: Most important info immediately visible
+- **Exceed expectations**: Add helpful context, trends, comparisons
+- **Create delight**: Use progressive disclosure to reduce overwhelm
+- **Maintain consistency**: Follow the same patterns as other reporting workflows
+
 ## Output Requirements
 
 Your output MUST include:

.github/workflows/daily-multi-device-docs-tester.md

@@ -110,10 +110,53 @@ Organize findings by severity:
 
 ## Step 5: Report Results
 
-Follow the **Report Structure Guidelines** from shared/reporting.md:
-- Use h3 (###) or lower for all headers (not h2 or h1)
-- Wrap detailed results in `<details><summary><b>Section Name</b></summary>` tags
-- Keep critical information visible, hide verbose details
+## 📝 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 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")
+- 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:
+- Detailed analysis and verbose data
+- Per-item breakdowns when there are many items
+- Complete logs, traces, or raw data
+- Secondary information and extra context
+
+Example:
+```markdown
+<details>
+<summary><b>View Detailed Analysis</b></summary>
+
+[Long detailed content here...]
+
+</details>
+```
+
+### 3. Report Structure Pattern
+
+Your report should follow this structure for optimal readability:
+
+1. **Brief Summary** (always visible): 1-2 paragraph overview of key findings
+2. **Key Metrics/Highlights** (always visible): Critical information and important statistics
+3. **Detailed Analysis** (in `<details>` tags): In-depth breakdowns, verbose data, complete lists
+4. **Recommendations** (always visible): Actionable next steps and suggestions
+
+### Design Principles
+
+Create reports that:
+- **Build trust through clarity**: Most important info immediately visible
+- **Exceed expectations**: Add helpful context, trends, comparisons
+- **Create delight**: Use progressive disclosure to reduce overwhelm
+- **Maintain consistency**: Follow the same patterns as other reporting workflows
 
 If issues are detected, create a GitHub issue titled "🔍 Multi-Device Docs Testing Report - [Date]" with: