Skip to content

Normalize report formatting in org-health-report and daily-safe-outputs-conformance workflows #17727

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Feb 22, 2026
Merged

Normalize report formatting in org-health-report and daily-safe-outputs-conformance workflows #17727

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b6c036b
Initial plan
Copilot Feb 22, 2026
12a20ca
Normalize report formatting for org-health-report and daily-safe-outp…
Copilot Feb 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 20 additions & 9 deletions .github/workflows/daily-safe-outputs-conformance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,17 @@ Analyze the output from `/tmp/conformance-results.txt`:
- REQ-001 through REQ-003: Specification requirements
- IMP-001 through IMP-003: Implementation requirements

## 📝 Report Formatting Guidelines

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

The issue title serves as the document title, so all content headers in the issue body should start at h3:
- Use `###` for main sections (e.g., "### Conformance Check Failure", "### Problem Description")
- Use `####` for subsections (e.g., "#### Affected Files", "#### Steps")
- Never use `##` (h2) or `#` (h1) in the issue body

**Wrap long sections in `<details><summary><b>Section Name</b></summary>` tags to improve readability and reduce scrolling.**
Comment on lines +90 to +99
Copy link

Copilot AI Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Report Formatting Guidelines" section is incomplete compared to the established pattern in compliant workflows (daily-observability-report.md:39-99, daily-team-status.md:52-98, copilot-pr-merged-report.md:150-196). The complete pattern includes:

  1. Opening with "CRITICAL: Follow these formatting guidelines to create well-structured, readable reports:"
  2. Numbered subsections: "### 1. Header Levels", "### 2. Progressive Disclosure", "### 3. Report Structure Pattern"
  3. A "### Design Principles" subsection

This section is missing the "CRITICAL" emphasis, numbered subsections, "Report Structure Pattern", and "Design Principles" that provide important context about how to structure reports for optimal readability.

Copilot uses AI. Check for mistakes.

## Phase 3: Generate Agentic Tasks

For each conformance issue found, create a GitHub issue using the `create_issue` tool with the following structure:
Expand All @@ -100,39 +111,39 @@ Example: `SEC-001: Agent job in workflow X has write permissions`
**Body Format**:

```markdown
## Conformance Check Failure
### Conformance Check Failure

**Check ID**: [CHECK_ID]
**Severity**: [CRITICAL/HIGH/MEDIUM/LOW]
**Category**: [Security/Usability/Specification/Implementation]

## Problem Description
### Problem Description

[Detailed description of what conformance check failed and why it matters]

## Affected Components
### Affected Components

- **Files**: [List specific files affected]
- **Workflows**: [List workflows if applicable]
- **Handlers**: [List handler files if applicable]

## Current Behavior
### Current Behavior

[Describe what the code currently does that violates conformance]

## Expected Behavior
### Expected Behavior

[Describe what the specification requires]

## Remediation Steps
### Remediation Steps

This task can be assigned to a Copilot coding agent with the following steps:

1. [Specific action 1]
2. [Specific action 2]
3. [Specific action 3]

## Verification
### Verification

After remediation, verify the fix by running:

Expand All @@ -142,7 +153,7 @@ bash scripts/check-safe-outputs-conformance.sh

The check [CHECK_ID] should pass without errors.

## References
### References

- Safe Outputs Specification: docs/src/content/docs/reference/safe-outputs-specification.md
- Conformance Checker: scripts/check-safe-outputs-conformance.sh
Expand All @@ -162,7 +173,7 @@ The check [CHECK_ID] should pass without errors.
If multiple similar issues are found (e.g., 3 handlers missing the same validation), consider creating ONE issue that covers all of them with a checklist:

```markdown
## Affected Components
### Affected Components

- [ ] Handler 1: actions/setup/js/handler1.cjs
- [ ] Handler 2: actions/setup/js/handler2.cjs
Expand Down
57 changes: 43 additions & 14 deletions .github/workflows/org-health-report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -339,18 +339,44 @@ Create a comprehensive markdown report with the following sections:
- Brief analysis of what the metrics mean
- Suggestions for maintainers on where to focus

## 📝 Report Formatting Guidelines

**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., "### 📊 Volume Metrics", "### Summary")
- Use `####` for subsections (e.g., "#### Overall Status", "#### Recent Activity")
- Never use `##` (h2) or `#` (h1) in the report body

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

Use collapsible sections for:
- "Top 10 Most Active Authors" table
- Full data and methodology details
- Any other verbose tables or data

Example:
```markdown
<details>
<summary><b>Top 10 Most Active Authors</b></summary>

[Author table here...]

</details>
```

Copy link

Copilot AI Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Report Formatting Guidelines" section is incomplete compared to the established pattern in compliant workflows (daily-observability-report.md, daily-team-status.md, copilot-pr-merged-report.md). The complete pattern includes:

  1. Opening with "CRITICAL: Follow these formatting guidelines to create well-structured, readable reports:"
  2. Numbered subsections: "### 1. Header Levels", "### 2. Progressive Disclosure", "### 3. Report Structure Pattern"
  3. A "### Design Principles" subsection

This section is missing the "CRITICAL" emphasis, numbered subsections, "Report Structure Pattern", and "Design Principles" that provide important context about how to structure reports for optimal readability.

Suggested change
### 3. Report Structure Pattern
Structure the report to surface the most important insights first, then progressively add detail:
- Start with an executive summary that highlights key findings and overall health.
- Follow with high-level metrics sections (e.g., activity, quality, risk) using consistent headings.
- Place detailed tables, methodology notes, and long explanations inside collapsible `<details>` sections.
- Keep section ordering consistent across runs so readers know where to find information.
### Design Principles
- **Clarity first:** Use concise, descriptive headings and avoid jargon where possible.
- **Scannability:** Optimize for readers who skim; use bullets, short paragraphs, and consistent section ordering.
- **Progressive disclosure:** Put critical insights in the open and defer supporting detail to collapsible sections.
- **Consistency across workflows:** Align formatting and structure with other organization reports to reduce cognitive load.
- **Accessibility:** Ensure that headings, lists, and code blocks use valid Markdown so reports render correctly in all clients.

Copilot uses AI. Check for mistakes.
### Phase 6: Create Discussion Report

Use the `create discussion` safe-output to publish the report:

```markdown
# Organization Health Report - [Date]
### 🏥 Organization Health Report - [Date]

[Executive Summary]

## 📊 Volume Metrics
### 📊 Volume Metrics

### Overall Status
#### Overall Status

| Metric | Count |
|--------|-------|
Expand All @@ -359,7 +385,7 @@ Use the `create discussion` safe-output to publish the report:
| Total Open PRs | X |
| Total Closed PRs | X |

### Recent Activity (7 Days)
#### Recent Activity (7 Days)

| Metric | Count |
|--------|-------|
Expand All @@ -368,7 +394,7 @@ Use the `create discussion` safe-output to publish the report:
| PRs Opened | X |
| PRs Closed | X |

### Recent Activity (30 Days)
#### Recent Activity (30 Days)

| Metric | Count |
|--------|-------|
Expand All @@ -377,60 +403,63 @@ Use the `create discussion` safe-output to publish the report:
| PRs Opened | X |
| PRs Closed | X |

## 🏆 Top 5 Most Active Repositories
### 🏆 Top 5 Most Active Repositories

| Repository | Recent Issues | Recent PRs | Comments | Activity Score |
|------------|---------------|------------|----------|----------------|
| repo1 | X | X | X | X |
| repo2 | X | X | X | X |
...

## 👥 Top 10 Most Active Authors
<details>
<summary><b>Top 10 Most Active Authors</b></summary>

| Author | Issues Opened | PRs Opened | Activity Score |
|--------|---------------|------------|----------------|
| user1 | X | X | X |
| user2 | X | X | X |
...

## 🔥 High-Activity Unresolved Items
</details>

### 🔥 High-Activity Unresolved Items

### Hot Issues (Need Attention)
#### Hot Issues (Need Attention)

| Issue | Repository | Comments | Age (days) | Link |
|-------|------------|----------|------------|------|
| #123: Title | repo | X | X | [View](#) |
...

### Hot PRs (Need Review)
#### Hot PRs (Need Review)

| PR | Repository | Comments | Age (days) | Link |
|----|------------|----------|------------|------|
| #456: Title | repo | X | X | [View](#) |
...

## ⚠️ Items Needing Attention
### ⚠️ Items Needing Attention

- **Stale Issues**: X issues open for 30+ days with no recent activity
- **Stale PRs**: X PRs open for 30+ days with no recent activity
- **Unassigned Issues**: X open issues without assignees
- **Unlabeled Issues**: X open issues without labels

## 💡 Commentary and Recommendations
### 💡 Commentary and Recommendations

[Analysis of the metrics and suggestions for where maintainers should focus their attention]

<details>
<summary><b>Full Data and Methodology</b></summary>

## Data Collection
#### Data Collection

- **Date Range**: [dates]
- **Repositories Analyzed**: X public, non-archived repositories
- **Issues Analyzed**: X issues
- **PRs Analyzed**: X pull requests

## Methodology
#### Methodology

- Data collected using GitHub API via MCP server
- Analyzed using Python pandas for efficient data processing
Expand Down