[workflow-style] Normalize report formatting for static-analysis-report

[github-actions]

Workflow to Update

Workflow File: .github/workflows/static-analysis-report.md
Issue: This workflow generates static analysis reports with templates that use h2 (##) headers, which should be h3 (###) for proper document hierarchy

Required Changes

Update the discussion template to use proper header levels across all sections.

1. Fix Header Levels in Discussion Template

The discussion template (lines 256-361) uses many ## headers which should be ###:

Main sections to update:

• ## Analysis Summary → ### Analysis Summary
• ## Clustered Findings by Tool and Type → ### Clustered Findings by Tool and Type
• ## Top Priority Issues → ### Top Priority Issues
• ## Fix Suggestion for [Selected Issue Type] → ### Fix Suggestion for [Selected Issue Type]
• ## All Findings Details → ### All Findings Details
• ## Historical Trends → ### Historical Trends
• ## Recommendations → ### Recommendations
• ## Next Steps → ### Next Steps

Subsections to update:

• ### Findings by Tool → #### Findings by Tool
• ### Zizmor Security Findings → #### Zizmor Security Findings
• ### Poutine Supply Chain Findings → #### Poutine Supply Chain Findings
• ### Actionlint Linting Issues → #### Actionlint Linting Issues
• ### 1. [Most Common/Severe Issue] → #### 1. [Most Common/Severe Issue]
• ### Cluster Details → #### Cluster Details
• ### [Workflow Name 1] → #### [Workflow Name 1]
• ### New Issues → #### New Issues
• ### Resolved Issues → #### Resolved Issues

2. Add Formatting Guidelines

Add this section before Phase 5 (around line 241):

### Report Formatting Guidelines

**Header Hierarchy**: Use h3 (###) or lower for all headers in the static analysis report. The discussion title serves as h1.

**Structure**:
- Main report sections: h3 (###) - e.g., "### Analysis Summary"
- Subsections and details: h4 (####) - e.g., "#### Zizmor Security Findings"
- Nested details: h5 (#####) if needed

**Progressive Disclosure**: Use `<details>` tags to collapse verbose content like individual workflow findings (as shown in template).

3. Update Template Systematically

In the discussion template (lines 256-361):

1. Replace all main section ## with ###
2. Replace all subsection ### with ####
3. Keep the <details> structure (already good)

Positive Notes:

• The workflow already uses <details> tags for "Detailed Findings by Workflow"
• Tables are used effectively for clustering findings
• The structure is clear and comprehensive

Design Principles

The updated workflow will create reports that:

1. Build trust through clarity: Proper hierarchy makes security findings easier to navigate
2. Maintain consistency: Follows patterns from other security/audit workflows
3. Improve prioritization: Clear hierarchy helps readers find critical issues quickly

Example Reference

See audit-workflows.md (after it's updated) for a similar security/audit workflow with proper header usage.

Testing

After updating:

1. Run the workflow with workflow_dispatch
2. Check the generated discussion for proper header hierarchy
3. Verify security findings sections use h3/h4 appropriately
4. Confirm the <details> section maintains proper nesting

AI generated by Workflow Normalizer

• expires on Jan 30, 2026, 12:24 PM UTC