Skip to content

Add shared reporting guidelines to non-compliant workflows#10877

Merged
pelikhan merged 3 commits intomainfrom
copilot/normalize-markdown-formatting
Jan 20, 2026
Merged

Add shared reporting guidelines to non-compliant workflows#10877
pelikhan merged 3 commits intomainfrom
copilot/normalize-markdown-formatting

Conversation

Copy link
Contributor

Copilot AI commented Jan 20, 2026

Four reporting workflows (smoke-claude, smoke-codex, smoke-copilot, poem-bot) lacked formatting standards, resulting in inconsistent report output. These workflows create GitHub issues and discussions without guidance on header hierarchy, progressive disclosure, or structure.

Changes

Added shared/reporting.md import to workflow frontmatter:

# Before
engine: copilot
network:
  allowed: [defaults]

# After  
engine: copilot
imports:
  - shared/reporting.md
network:
  allowed: [defaults]

Impact

Workflows now have access to standardized formatting guidelines embedded in compiled .lock.yml files:

  • Header levels: h3 or lower (preserves document hierarchy)
  • Progressive disclosure: <details> tags for verbose content
  • Report structure: Summary → Critical info → Detailed sections → Recommendations
  • When to collapse: Lists 10+ items, raw logs, per-file stats

Modified Workflows

  • smoke-claude.md - Added to existing imports
  • smoke-codex.md - Added to existing imports
  • smoke-copilot.md - Created imports section
  • poem-bot.md - Created imports section

Each workflow's compiled lock file now includes ~70 lines of formatting guidance available to the AI agent during execution.

Original prompt

This section details on the original issue you should resolve

<issue_title>[workflow-style] Normalize markdown formatting across reporting workflows</issue_title>
<issue_description>### Overview

Multiple reporting workflows lack proper markdown formatting guidelines. This creates inconsistent report formatting across the repository.

Affected Workflows

🔴 Non-Compliant (No formatting guidelines)

These workflows create reports but have no formatting instructions:

  1. smoke-claude.md - Creates test result issues
  2. smoke-codex.md - Creates test result issues
  3. smoke-copilot.md - Creates test result issues
  4. poem-bot.md - Creates discussion posts

Recommendation: These workflows should import shared/reporting.md:

imports:
  - shared/reporting.md

⚠️ Partial Compliance (Missing progressive disclosure)

These workflows mention h3 headers but don't explain <details> tags (showing top 10):

  1. agent-performance-analyzer.md - Creates performance analysis discussions
  2. auto-triage-issues.md - Creates triage reports
  3. breaking-change-checker.md - Creates breaking change issues
  4. ci-doctor.md - Creates CI health reports
  5. cli-consistency-checker.md - Creates consistency reports
  6. cli-version-checker.md - Creates version check issues
  7. copilot-cli-deep-research.md - Creates research discussions
  8. craft.md - Creates workflow generation summaries
  9. duplicate-code-detector.md - Creates code quality issues
  10. docs-noob-tester.md - Creates documentation test reports

... and 14 more (see analysis in comments)

Recommendation: Add a "Formatting Guidelines" section explaining progressive disclosure.

Required Formatting Standards

All reporting workflows should follow these standards from shared/reporting.md:

1. Header Levels

Rule: Use h3 (###) or lower for all headers in reports to maintain proper document hierarchy.

Rationale: The issue/discussion title is already h1, and system UI may add h2 elements.

2. Progressive Disclosure

Rule: Use <details><summary><b>Section Name</b></summary> tags for long content.

Example:

### Summary
[2-3 paragraphs with key findings - always visible]

<details>
<summary><b>View Full Analysis</b></summary>

[Detailed analysis, long lists, raw data]

</details>

When to use:

  • Lists with 10+ items
  • Detailed technical breakdowns
  • Per-file or per-author statistics
  • Historical data or trends
  • Raw logs or test output

3. Report Structure

Follow this pattern (inspired by Airbnb's design principles):

  1. Brief summary (2-3 paragraphs) - always visible
  2. Key metrics/highlights - always visible
  3. Detailed analysis - in <details> tags
  4. Recommendations - always visible

Implementation Options

Option 1: Import Shared Guidelines (Recommended)

Add to workflow frontmatter:

imports:
  - shared/reporting.md

Advantages:

  • Consistent standards across all workflows
  • Single source of truth
  • Automatic updates when standards evolve

Option 2: Inline Guidelines

Add a "Report Formatting" section to the workflow with:

  • Header level instructions (h3 or lower)
  • Progressive disclosure examples
  • Report structure template

Use when: Workflow has unique reporting needs

Benefits of Standardization

User Experience:

  • ✅ Easier to scan reports for important information
  • ✅ Reduced scrolling and cognitive load
  • ✅ Consistent experience across all workflows
  • ✅ Better mobile readability

Technical Benefits:

  • ✅ Easier to maintain workflows
  • ✅ Clearer expectations for AI agents
  • ✅ Better integration with GitHub UI
  • ✅ Improved accessibility

Design Principles (Airbnb-Inspired)

Trust Through Clarity: Important information visible upfront
Exceeding Expectations: Add helpful context and trends
Creating Delight: Use progressive disclosure to reduce overwhelm
Consistency: Same patterns across all reports

Next Steps

Phase 1: Fix non-compliant workflows (4 workflows)

  • Add shared/reporting.md import
  • Test report formatting

Phase 2: Improve partial compliance (24 workflows)

  • Add progressive disclosure guidelines
  • Update report templates
  • Show before/after examples

Phase 3: Monitor compliance

  • Add to workflow creation checklist
  • Update documentation
  • Create linting rules (future)

Reference Examples

Excellent formatting:

  • daily-repo-chronicle.md - Newspaper style with progressive disclosure
  • audit-workflows.md - Comprehensive audit with collapsed details
  • static-analysis-report.md - Security findings with detailed views

Related Issues

  • #aw_multi_device_001 - Normalize formatting for daily-multi-device-docs-tester
  • #aw_team_evolution_002 - Add progressive disclosure to daily-team-evolution-insights

Success Criteria

A workflow has proper formatting guidelines when:

  • ✅ It imports `shared/re...

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
Copilot AI changed the title [WIP] Normalize markdown formatting across reporting workflows Add shared reporting guidelines to non-compliant workflows Jan 20, 2026
Copilot AI requested a review from mnkiefer January 20, 2026 17:17
@pelikhan pelikhan marked this pull request as ready for review January 20, 2026 19:24
@pelikhan pelikhan merged commit edf724d into main Jan 20, 2026
@pelikhan pelikhan deleted the copilot/normalize-markdown-formatting branch January 20, 2026 19:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[workflow-style] Normalize markdown formatting across reporting workflows

3 participants