-
Notifications
You must be signed in to change notification settings - Fork 296
Description
Workflows to Update
The following workflows generate reports but don't include proper markdown style guidelines in their prompts:
| Workflow File | Issues Found |
|---|---|
.github/workflows/org-health-report.md |
Discussion template uses h1 (# Organization Health Report) and h2 (## 📊 Volume Metrics) headers; no "Report Formatting Guidelines" section |
.github/workflows/daily-safe-outputs-conformance.md |
Issue body template uses h2 headers (## Conformance Check Failure, ## Problem Description, ## Affected Components); no formatting guidelines |
Required Changes
For each workflow listed above, update the prompt to include these formatting guidelines:
1. Header Levels
Add instruction: "Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy."
For org-health-report.md, update the discussion template to start at h3:
### 🏥 Organization Health Report - [Date]
### 📊 Volume Metrics
#### Overall Status
...For daily-safe-outputs-conformance.md, update the issue body template to use h3:
### Conformance Check Failure
**Check ID**: [CHECK_ID]
...
### Problem Description
...
### Affected Components
...2. Progressive Disclosure
Add instruction: "Wrap long sections in <details><summary><b>Section Name</b></summary> tags to improve readability and reduce scrolling."
For org-health-report.md, wrap verbose sections like "Top 10 Most Active Authors" and "Full Data and Methodology" in details tags.
3. Report Formatting Guidelines Section
Add a dedicated ## 📝 Report Formatting Guidelines section (like other compliant workflows such as daily-observability-report.md, daily-team-status.md, copilot-pr-merged-report.md) before the output template:
## 📝 Report Formatting Guidelines
**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**
The discussion/issue title serves as h1, so all content headers should start at h3:
- Use `###` for main sections (e.g., "### 📊 Volume Metrics", "### Summary")
- Use `####` for subsections (e.g., "#### Overall Status", "#### Recent Activity")
**Wrap long sections in `<details><summary><b>Section Name</b></summary>` tags to improve readability and reduce scrolling.**
Example:
<details>
<summary><b>Full Details</b></summary>
[Detailed content here...]
</details>Design Principles (Airbnb-Inspired)
The updated workflows should 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
Example Reference
See workflows like daily-repo-chronicle, daily-team-status, daily-observability-report, and copilot-pr-merged-report for good examples of structured reporting with proper h3+ headers and <details> tags.
Agent Task
Update each workflow file listed in the table above to:
- Add a
## 📝 Report Formatting Guidelinessection - Fix the output template headers to start at h3 (###)
- Wrap verbose content in
<details><summary><b>...</b></summary>tags - Run
make recompileafter making changes to regenerate lock files
Generated by Workflow Normalizer
- expires on Feb 23, 2026, 1:41 PM UTC