Add report formatting guidelines to agent-performance-analyzer workflow

[Copilot]

The agent-performance-analyzer meta-orchestrator generates complex performance reports (quality metrics, effectiveness scores, behavioral patterns) but lacked formatting guidelines, resulting in overwhelming walls of text.

Changes

• Added import: shared/reporting.md in frontmatter for standard formatting guidelines
• Added inline formatting section: Inserted "Report Formatting Guidelines" after role description with:
  • Header hierarchy rules (h3+ only, preserves document structure)
  • Progressive disclosure directives (wrap detailed metrics in <details><summary> tags)
  • Concrete report structure pattern showing what stays visible (summary, critical findings, recommendations) vs. what collapses (detailed metrics, agent breakdowns, trend charts)
  • Design principles for consistency with other meta-orchestrator reports

Example Structure

### Performance Summary
- Total agents analyzed: 42
- Critical issues found: 3

### Critical Findings
[Always visible - urgent items requiring action]

<details>
<summary><b>View Detailed Quality Analysis</b></summary>

[Full metrics tables, agent-by-agent scores]

</details>

### Recommendations
[Actionable next steps - keep visible]

Follows patterns established in audit-workflows.md and daily-issues-report.md.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[workflow-style] Normalize report formatting for agent-performance-analyzer</issue_title>
<issue_description>### Workflow to Update

Workflow File: .github/workflows/agent-performance-analyzer.md

Issue: This daily meta-orchestrator workflow analyzes AI agent performance and creates issues/discussions but doesn't include markdown style guidelines. Since it generates structured reports about agent behavior and effectiveness, consistent formatting would significantly improve readability.

Why This Matters

The agent-performance-analyzer is a meta-orchestrator that evaluates agent quality and creates detailed performance reports. These reports contain complex data (quality metrics, effectiveness scores, behavioral patterns) that would benefit greatly from progressive disclosure and proper hierarchy.

Required Changes

Update the workflow prompt to include these formatting guidelines (add after the meta-orchestrator description):

1. Header Levels

Add instruction: "Use h3 (###) or lower for all headers in your reports to maintain proper document hierarchy."

Rationale: Agent performance reports contain multiple levels of information (quality analysis, effectiveness measurement, behavioral patterns). Using h2/h1 breaks the document hierarchy since the issue/discussion title is already h1.

2. Progressive Disclosure

Add instruction: "Wrap detailed analysis sections in <details><summary><b>Section Name</b></summary> tags to improve readability and reduce scrolling."

Example:

<details>
<summary><b>Full Performance Metrics</b></summary>

[Detailed metrics tables, agent-by-agent breakdowns, historical trends]

</details>

Rationale: Performance reports contain extensive tables (quality scores, completion rates, resource efficiency) that can overwhelm readers. Progressive disclosure keeps the summary visible while hiding details until needed.

3. Report Structure

Suggest adding this structure pattern:

### Performance Summary
- Total agents analyzed: [N]
- Overall effectiveness score: [X%]
- Critical issues found: [N]

### Critical Findings
[Always visible - quality issues, failing agents, urgent recommendations]

<details>
<summary><b>View Detailed Quality Analysis</b></summary>

[Full quality metrics, agent-by-agent scores, trend charts]

</details>

<details>
<summary><b>View Effectiveness Metrics</b></summary>

[Task completion rates, decision quality, resource efficiency tables]

</details>

### Recommendations
[Actionable next steps - keep visible]

Design Principles (Airbnb-Inspired)

The updated workflow should create reports that:

1. Build trust through clarity: Most important findings (critical issues, overall health) immediately visible
2. Exceed expectations: Add helpful context like trend comparisons, historical performance
3. Create delight: Use progressive disclosure to present complex data without overwhelming
4. Maintain consistency: Follow the same patterns as other meta-orchestrator reports

Import Statement to Add

Add this to the imports: section in the frontmatter:

imports:
  - shared/reporting.md

This automatically loads the formatting guidelines into the agent's context.

Example Reference

See workflows like audit-workflows.md or daily-issues-report.md for good examples of structured reporting with progressive disclosure.

Agent Task

1. Add shared/reporting.md to the imports section
2. Add formatting guidelines to the prompt instructions
3. Test by running the workflow and reviewing the generated report format
4. Ensure critical findings stay visible while detailed metrics are collapsible

AI generated by Workflow Normalizer

• expires on Jan 29, 2026, 12:27 PM UTC

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

• Fixes [workflow-style] Normalize report formatting for agent-performance-analyzer #11270

---

💡 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.