[workflow-style] Normalize report formatting for non-compliant workflows #24194
Description
Workflows to Update
The following active workflows generate reports but have markdown style violations — using h1/h2 headers where h3 or lower is required:
| Workflow File | Issues Found |
|---|---|
.github/workflows/daily-safe-output-optimizer.md |
Issue body template uses h1 (# Improve [Tool Name]...) |
.github/workflows/dev-hawk.md |
PR comment templates use h1 (# ✅ Dev Hawk Report) and h2 (## Root Cause Analysis, ## Error Details) |
.github/workflows/pr-nitpick-reviewer.md |
Discussion report uses h1 (# PR Nitpick Review Summary) and h2 (## Pull Request Overview, ## Nitpick Categories) |
.github/workflows/security-review.md |
Review submission template uses h2 (## Overall Observations) |
Reference compliant workflows: daily-observability-report.md and archie.md already follow all style guidelines and can serve as examples.
Required Changes
For each workflow listed above, update the report/comment templates to follow these formatting guidelines:
1. Header Levels
Replace all h1 (#) and h2 (##) headers in generated output (issue bodies, PR comments, discussion bodies, review submissions) with h3 (###) or lower.
Before (non-compliant):
# PR Nitpick Review Summary - 2026-04-02
## Pull Request Overview
...
### Naming and ConventionsAfter (compliant):
### PR Nitpick Review Summary - 2026-04-02
#### Pull Request Overview
...
##### Naming and Conventions2. Progressive Disclosure
Wrap long sections in <details><summary><b>Section Name</b></summary> tags to improve readability.
Example from daily-observability-report.md (already compliant):
<details>
<summary><b>📋 Detailed Run Analysis</b></summary>
#### Firewall-Enabled Runs
...
</details>Apply this pattern in pr-nitpick-reviewer.md and dev-hawk.md for verbose sections.
3. Report Structure
Suggested structure for each workflow's output:
- Brief summary (always visible): 1-2 sentences with outcome
- Key metrics or highlights (always visible): status, counts
- Detailed sections (in
<details>tags): full analysis, error logs, per-file breakdown - Recommendations or next steps (always visible): actionable items
Per-Workflow Specific Guidance
daily-safe-output-optimizer.md
In Phase 6, the issue template body starts with:
# Improve [Tool Name] Description to Prevent Agent ErrorsChange to (the title is already in the create-issue title field — no need to repeat it as h1 in the body):
### Summary
...dev-hawk.md
The three comment templates (Success, Failure with root cause, Failure without root cause) use h1 as the first line:
# ✅ Dev Hawk Report - SuccessChange to:
### ✅ Dev Hawk Report - SuccessAnd downgrade all ## headers to ### throughout the comment templates.
pr-nitpick-reviewer.md
Step 5's report structure starts with:
# PR Nitpick Review Summary - [DATE]
## Pull Request Overview
## Nitpick Categories
### 1. Naming and ConventionsChange to:
### PR Nitpick Review Summary - [DATE]
#### Pull Request Overview
#### Nitpick Categories
##### 1. Naming and ConventionsAlso add instruction text: "Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy."
security-review.md
In Step 4, the submit_pull_request_review example uses:
"body": "## Overall Observations\n\nI noticed a few patterns..."Change to:
"body": "### Overall Observations\n\nI noticed a few patterns..."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
daily-observability-report.mdandarchie.md
Agent Task
Update each workflow file listed in the table above to include the corrected formatting in the output templates. After changes, recompile with make recompile.
References:
- §23927294434 — Workflow Normalizer run that identified these issues
Generated by Workflow Normalizer · ● 573.9K · ◷
- expires on Apr 3, 2026, 11:56 PM UTC