diff --git a/.github/workflows/commit-changes-analyzer.md b/.github/workflows/commit-changes-analyzer.md index bfe0dbc9ee2..e06e42c0708 100644 --- a/.github/workflows/commit-changes-analyzer.md +++ b/.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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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 diff --git a/.github/workflows/copilot-pr-merged-report.md b/.github/workflows/copilot-pr-merged-report.md index 60c7b3b4f8f..21298822c52 100644 --- a/.github/workflows/copilot-pr-merged-report.md +++ b/.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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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 diff --git a/.github/workflows/copilot-pr-nlp-analysis.md b/.github/workflows/copilot-pr-nlp-analysis.md index 85706d7e6b8..b62a9f6acad 100644 --- a/.github/workflows/copilot-pr-nlp-analysis.md +++ b/.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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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]` diff --git a/.github/workflows/copilot-pr-prompt-analysis.md b/.github/workflows/copilot-pr-prompt-analysis.md index bf03ef3c144..d90446fcbd8 100644 --- a/.github/workflows/copilot-pr-prompt-analysis.md +++ b/.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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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]` diff --git a/.github/workflows/copilot-session-insights.md b/.github/workflows/copilot-session-insights.md index b760cd4ced8..bf5d8bad2bd 100644 --- a/.github/workflows/copilot-session-insights.md +++ b/.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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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**: diff --git a/.github/workflows/daily-mcp-concurrency-analysis.md b/.github/workflows/daily-mcp-concurrency-analysis.md index f6a8befaca0..07764a7eeea 100644 --- a/.github/workflows/daily-mcp-concurrency-analysis.md +++ b/.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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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: diff --git a/.github/workflows/daily-multi-device-docs-tester.md b/.github/workflows/daily-multi-device-docs-tester.md index 63ed78f14b5..79fe572ebf2 100644 --- a/.github/workflows/daily-multi-device-docs-tester.md +++ b/.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 `
Section Name` 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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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: diff --git a/.github/workflows/daily-safe-output-optimizer.md b/.github/workflows/daily-safe-output-optimizer.md index 7533d7dbedc..3e4107a5a55 100644 --- a/.github/workflows/daily-safe-output-optimizer.md +++ b/.github/workflows/daily-safe-output-optimizer.md @@ -392,6 +392,54 @@ Organize persistent data in `/tmp/gh-aw/cache-memory/safe-output-optimizer/`: └── historical-trends.json # Trend analysis over time ``` +## 📝 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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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: diff --git a/.github/workflows/daily-secrets-analysis.md b/.github/workflows/daily-secrets-analysis.md index 68de5eead3a..b2b06a3feed 100644 --- a/.github/workflows/daily-secrets-analysis.md +++ b/.github/workflows/daily-secrets-analysis.md @@ -194,6 +194,54 @@ echo "Stats saved for tomorrow's comparison" ## Generate Discussion 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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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 your findings: ### Report Structure diff --git a/.github/workflows/daily-syntax-error-quality.md b/.github/workflows/daily-syntax-error-quality.md index 0dafee77138..300c3ec3972 100644 --- a/.github/workflows/daily-syntax-error-quality.md +++ b/.github/workflows/daily-syntax-error-quality.md @@ -340,6 +340,54 @@ Create a detailed evaluation for each test case: ## Phase 6: Create Issue with Suggestions +## 📝 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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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 + **Only create an issue if**: - Average score < 70 across all test cases, OR - Any individual test case scores < 55, OR diff --git a/.github/workflows/daily-team-evolution-insights.md b/.github/workflows/daily-team-evolution-insights.md index 637ce1f3e06..f82ea6244db 100644 --- a/.github/workflows/daily-team-evolution-insights.md +++ b/.github/workflows/daily-team-evolution-insights.md @@ -46,42 +46,33 @@ Analyze the last 24 hours of repository activity to extract meaningful insights - Emerging technologies or practices - Team dynamics and productivity -## Formatting Guidelines +## 📝 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., "### 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") - Never use `##` (h2) or `#` (h1) in the report body ### 2. Progressive Disclosure -**Wrap detailed sections in `
Section Name` tags to improve readability and reduce scrolling.** +**Wrap long sections in `
Section Name` tags to improve readability and reduce scrolling.** Use collapsible sections for: -- Individual contributor activity breakdowns -- Detailed commit histories and file change lists -- Full PR/issue/discussion activity logs -- Complete code review conversations -- Raw data, statistics, and technical breakdowns +- 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
-Detailed Activity Breakdown +View Detailed Analysis -### Individual Contributions - -#### `@contributor1` -- 15 commits across 23 files -- 2 PRs merged (feat-x, fix-y) -- 8 code review comments - -#### `@contributor2` -- ... +[Long detailed content here...]
``` @@ -90,19 +81,18 @@ Example: Your report should follow this structure for optimal readability: -1. **Executive Summary** (always visible): 2-3 paragraphs with key insights about team evolution -2. **Key Observations** (always visible): Focus areas, velocity, collaboration, innovation highlights -3. **Detailed Activity Analysis** (in `
` tags): Per-contributor breakdowns, commit histories -4. **Trends & Patterns** (always visible): What the activity means for the team's evolution -5. **Recommendations** (always visible): Actionable suggestions for improvement +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 `
` 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 meaningful insights (patterns, trends, observations) immediately visible -- **Exceed expectations**: Connect raw activity to strategic insights about team evolution -- **Create delight**: Use progressive disclosure to show supporting data without overwhelming the narrative -- **Maintain consistency**: Follow the same patterns as other daily reporting workflows +- **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 ## Current Context diff --git a/.github/workflows/daily-testify-uber-super-expert.md b/.github/workflows/daily-testify-uber-super-expert.md index 79c1f7f4aaa..ab1de8a5865 100644 --- a/.github/workflows/daily-testify-uber-super-expert.md +++ b/.github/workflows/daily-testify-uber-super-expert.md @@ -176,6 +176,54 @@ Calculate: ### 5. Generate Issue with Improvements +## 📝 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 `
Section Name` 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 +
+View Detailed Analysis + +[Long detailed content here...] + +
+``` + +### 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 `
` 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 detailed issue with this structure: ```markdown