Add shared reporting guidelines to non-compliant workflows#10877
Merged
Add shared reporting guidelines to non-compliant workflows#10877
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdimport to workflow frontmatter:Impact
Workflows now have access to standardized formatting guidelines embedded in compiled
.lock.ymlfiles:<details>tags for verbose contentModified Workflows
smoke-claude.md- Added to existing importssmoke-codex.md- Added to existing importssmoke-copilot.md- Created imports sectionpoem-bot.md- Created imports sectionEach 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:
Recommendation: These workflows should import
shared/reporting.md:These workflows mention h3 headers but don't explain
<details>tags (showing top 10):... 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:
When to use:
3. Report Structure
Follow this pattern (inspired by Airbnb's design principles):
<details>tagsImplementation Options
Option 1: Import Shared Guidelines (Recommended)
Add to workflow frontmatter:
Advantages:
Option 2: Inline Guidelines
Add a "Report Formatting" section to the workflow with:
Use when: Workflow has unique reporting needs
Benefits of Standardization
User Experience:
Technical Benefits:
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)
shared/reporting.mdimportPhase 2: Improve partial compliance (24 workflows)
Phase 3: Monitor compliance
Reference Examples
Excellent formatting:
daily-repo-chronicle.md- Newspaper style with progressive disclosureaudit-workflows.md- Comprehensive audit with collapsed detailsstatic-analysis-report.md- Security findings with detailed viewsRelated Issues
Success Criteria
A workflow has proper formatting guidelines when:
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.