Overview
Daily review of workflow activity from the last 24 hours identified 4 reporting workflows that are missing explicit markdown style formatting guidelines in their prompts. These workflows already use correct patterns in their output templates (### headers, <details> tags), but lack the explicit instruction text that guides the AI agent to follow these standards consistently.
Reviewed: 14 active reporting workflows
Compliant: 10 workflows ✅
Needs improvement: 4 workflows ⚠️
Workflows to Update
| Workflow File |
Issues Found |
.github/workflows/daily-safe-output-optimizer.md |
Missing explicit header level + <details> formatting guideline |
.github/workflows/spec-librarian.md |
Mentions progressive disclosure but missing explicit "Use h3+" instruction |
.github/workflows/design-decision-gate.md |
No explicit report formatting instruction despite using ### in templates |
.github/workflows/test-quality-sentinel.md |
No explicit report formatting instruction despite using ### in templates |
Required Changes
For each workflow listed above, add the following formatting guideline near the output/report section of the prompt (following the same pattern as compliant workflows like daily-compiler-quality.md line 563):
1. Header Levels
Add instruction:
Report Formatting: Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy. Wrap long sections in <details><summary>Section Name</summary> tags to improve readability and reduce scrolling.
2. Placement
Add this instruction in the "Output Requirements" or "Guidelines" section, near where the workflow instructs the agent to create the issue/discussion/comment.
3. Reference Implementations
See these workflows for examples of the correct pattern:
daily-compiler-quality.md — line 563daily-observability-report.md — line 374daily-secrets-analysis.md — line 295auto-triage-issues.md — line 200
View Detailed Findings per Workflow
daily-safe-output-optimizer.md
- Creates GitHub issues for tool description improvements
- Issue template already uses
### headers and <details> tags correctly (lines 233, 270, 274, 281)
- Missing: Explicit
Report Formatting guideline line in the Output Requirements section
spec-librarian.md
- Creates GitHub issues for package specification audits
- Issue template uses
### headers throughout
- Mentions "Use progressive disclosure: Wrap details in
<details> tags" in guidelines (line 331)
- Missing: Explicit header level guideline ("Use h3 (###) or lower")
design-decision-gate.md
- Adds PR review comments (blocking or approving)
- Comment templates use
### headers and <details> tags correctly (line 323)
- Missing: Any explicit formatting guideline for PR comment output
test-quality-sentinel.md
- Adds PR quality review comments
- Comment templates use
### headers and <details> tags (lines 393, 474)
- Missing: Any explicit formatting guideline for PR comment output
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
Agent Task
For each workflow file listed in the table above, add the Report Formatting guideline instruction near the output/report generation section. No structural changes needed — the templates are already correct. This is a small, targeted addition to make the instruction explicit and consistent across all workflows.
References: Workflow Normalizer run §24696479755
Generated by Workflow Normalizer · ● 1.9M · ◷
Overview
Daily review of workflow activity from the last 24 hours identified 4 reporting workflows that are missing explicit markdown style formatting guidelines in their prompts. These workflows already use correct patterns in their output templates (
###headers,<details>tags), but lack the explicit instruction text that guides the AI agent to follow these standards consistently.Reviewed: 14 active reporting workflows⚠️
Compliant: 10 workflows ✅
Needs improvement: 4 workflows
Workflows to Update
.github/workflows/daily-safe-output-optimizer.md<details>formatting guideline.github/workflows/spec-librarian.md.github/workflows/design-decision-gate.md###in templates.github/workflows/test-quality-sentinel.md###in templatesRequired Changes
For each workflow listed above, add the following formatting guideline near the output/report section of the prompt (following the same pattern as compliant workflows like
daily-compiler-quality.mdline 563):1. Header Levels
Add instruction:
2. Placement
Add this instruction in the "Output Requirements" or "Guidelines" section, near where the workflow instructs the agent to create the issue/discussion/comment.
3. Reference Implementations
See these workflows for examples of the correct pattern:
daily-compiler-quality.md— line 563daily-observability-report.md— line 374daily-secrets-analysis.md— line 295auto-triage-issues.md— line 200View Detailed Findings per Workflow
daily-safe-output-optimizer.md###headers and<details>tags correctly (lines 233, 270, 274, 281)Report Formattingguideline line in the Output Requirements sectionspec-librarian.md###headers throughout<details>tags" in guidelines (line 331)design-decision-gate.md###headers and<details>tags correctly (line 323)test-quality-sentinel.md###headers and<details>tags (lines 393, 474)Design Principles (Airbnb-Inspired)
The updated workflows should create reports that:
Agent Task
For each workflow file listed in the table above, add the
Report Formattingguideline instruction near the output/report generation section. No structural changes needed — the templates are already correct. This is a small, targeted addition to make the instruction explicit and consistent across all workflows.References: Workflow Normalizer run §24696479755