Workflows to Update
The following workflows generate structured reports via add-comment but don't import shared/reporting.md (the authoritative style guidelines):
| Workflow File |
Issues Found |
Active In Last 24h |
.github/workflows/test-quality-sentinel.md |
Missing explicit header level guidelines (no shared/reporting.md import) |
✅ Yes |
.github/workflows/dev-hawk.md |
Missing explicit header level guidelines (no shared/reporting.md import) |
✅ Yes |
.github/workflows/design-decision-gate.md |
Missing explicit header level guidelines (no shared/reporting.md import) |
✅ Yes |
Note: These workflows already use ### headers and <details> tags in their embedded templates (so they're partially compliant), but they lack the explicit style guidance that shared/reporting.md provides. Adding the import ensures the AI agent follows consistent formatting conventions even when generating output not covered by the template.
Required Changes
For each workflow listed above, add the following import to the frontmatter:
imports:
- shared/reporting.md # Add this line
This provides the agent with the full style guidelines:
1. Header Levels
The import adds explicit instruction: "Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy."
2. Progressive Disclosure
The import adds instruction: "Wrap long sections in <details><summary>Section Name</summary> tags to improve readability and reduce scrolling."
3. Report Structure Pattern
The import provides a complete report structure template with overview, critical info, collapsible details, and recommendations.
Design Principles (Airbnb-Inspired)
The updated workflows should create reports that:
- Build trust through clarity: Most important info immediately visible
- Exceed expectations: Add helpful context, trends, comparisons
- Create delight: Use progressive disclosure to reduce overwhelm
- Maintain consistency: Follow the same patterns as other reporting workflows
Example Reference
See compliant workflows like .github/workflows/daily-safe-output-optimizer.md or .github/workflows/spec-librarian.md for examples with shared/reporting.md imported.
Compliance Summary
Of the active reporting workflows reviewed:
| Status |
Count |
Workflows |
✅ Compliant (imports shared/reporting.md) |
6 |
daily-safe-output-optimizer, spec-librarian, approach-validator, api-consumption-report, daily-performance-summary, daily-observability-report |
| ⚠️ Needs Improvement |
3 |
test-quality-sentinel, dev-hawk, design-decision-gate |
Agent Task
Update each workflow file listed in the table above by adding shared/reporting.md to their imports list. Then run make recompile to regenerate the lock files.
References:
- §24428894426 — Workflow Normalizer run that generated this report
Generated by Workflow Normalizer · ● 2.7M · ◷
Workflows to Update
The following workflows generate structured reports via
add-commentbut don't importshared/reporting.md(the authoritative style guidelines):.github/workflows/test-quality-sentinel.mdshared/reporting.mdimport).github/workflows/dev-hawk.mdshared/reporting.mdimport).github/workflows/design-decision-gate.mdshared/reporting.mdimport)Note: These workflows already use
###headers and<details>tags in their embedded templates (so they're partially compliant), but they lack the explicit style guidance thatshared/reporting.mdprovides. Adding the import ensures the AI agent follows consistent formatting conventions even when generating output not covered by the template.Required Changes
For each workflow listed above, add the following import to the frontmatter:
This provides the agent with the full style guidelines:
1. Header Levels
The import adds explicit instruction: "Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy."
2. Progressive Disclosure
The import adds instruction: "Wrap long sections in
<details><summary>Section Name</summary>tags to improve readability and reduce scrolling."3. Report Structure Pattern
The import provides a complete report structure template with overview, critical info, collapsible details, and recommendations.
Design Principles (Airbnb-Inspired)
The updated workflows should create reports that:
Example Reference
See compliant workflows like
.github/workflows/daily-safe-output-optimizer.mdor.github/workflows/spec-librarian.mdfor examples withshared/reporting.mdimported.Compliance Summary
Of the active reporting workflows reviewed:
shared/reporting.md)daily-safe-output-optimizer,spec-librarian,approach-validator,api-consumption-report,daily-performance-summary,daily-observability-reporttest-quality-sentinel,dev-hawk,design-decision-gateAgent Task
Update each workflow file listed in the table above by adding
shared/reporting.mdto theirimportslist. Then runmake recompileto regenerate the lock files.References: