[WIP] Normalize header levels in static analysis report

[Copilot]

Normalize report formatting for static-analysis-report workflow

Objective: Update discussion template in .github/workflows/static-analysis-report.md to use proper header hierarchy (h3/h4) instead of h2/h3.

Completed Changes

• Analyze the workflow file and understand current structure
• Add formatting guidelines section before Phase 5 (line 241)
• Update main section headers from ## to ###:
  • Analysis Summary
  • Clustered Findings by Tool and Type
  • Top Priority Issues
  • Fix Suggestion for [Selected Issue Type]
  • All Findings Details
  • Historical Trends
  • Recommendations
  • Next Steps
• Update subsection headers from ### to ####:
  • Findings by Tool (line 263)
  • Zizmor Security Findings (line 273)
  • Poutine Supply Chain Findings (line 281)
  • Actionlint Linting Issues (line 287)
  • 1. [Most Common/Severe Issue] (line 295)
  • [Workflow Name 1] (line 320) → now #### with nested ##### for Issue Type
  • New Issues (line 341)
  • Resolved Issues (line 344)
• Verify changes compile correctly
• All changes committed and lock file updated

Summary of Changes

Added Formatting Guidelines Section (lines 239-248):

• Explains header hierarchy requirements (h3 for main sections, h4 for subsections)
• Documents structure expectations
• Notes progressive disclosure with <details> tags

Updated Discussion Template Headers:

• 8 main section headers: ## → ###
• 8 subsection headers: ### → ####
• 1 nested detail header: #### → ##### (Issue Type within Workflow details)
• All changes maintain document hierarchy with discussion title as h1

The workflow now follows proper header hierarchy patterns consistent with other security/audit workflows in the repository.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[workflow-style] Normalize report formatting for static-analysis-report</issue_title>
<issue_description>### 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

Comments on the Issue (you are @copilot in this section)

• Fixes [workflow-style] Normalize report formatting for static-analysis-report #11500

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.