[workflow-style] Normalize report formatting for 36 non-compliant workflows#43516
Conversation
Add missing Output Format guidance (h3 headers, progressive disclosure, report structure) to each non-compliant workflow as identified in the workflow style audit. Excludes agentic-token-audit.md which is upstream-managed (source: githubnext/agentic-ops@...). Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
Hey One item worth considering:
If you'd like a hand, you can assign this prompt to your coding agent:
|
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #43516 does not have the 'implementation' label and has 0 new lines of code in business logic directories (threshold: 100). |
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. Test Quality Sentinel skipped. |
|
✅ PR Code Quality Reviewer completed the code quality review. |
There was a problem hiding this comment.
Pull request overview
This PR standardizes report-formatting guidance across a large set of gh-aw markdown workflows by adding a ### Output Format section (and regenerating the corresponding .lock.yml files) so workflow outputs follow consistent structure and progressive disclosure patterns.
Changes:
- Appends
### Output Formatsections to the affected workflow.mdfiles with the missing formatting directives (headers, report structure, and/or<details>guidance). - Regenerates the associated
.lock.ymlfiles to reflect the updated workflow bodies.
Show a summary per file
| File | Description |
|---|---|
| .github/workflows/weekly-safe-outputs-spec-review.md | Adds ### Output Format guidance. |
| .github/workflows/weekly-safe-outputs-spec-review.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/weekly-editors-health-check.md | Adds ### Output Format guidance. |
| .github/workflows/weekly-editors-health-check.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/weekly-blog-post-writer.md | Adds ### Output Format guidance. |
| .github/workflows/weekly-blog-post-writer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/video-analyzer.md | Adds ### Output Format guidance. |
| .github/workflows/video-analyzer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/ubuntu-image-analyzer.md | Adds ### Output Format guidance. |
| .github/workflows/ubuntu-image-analyzer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/pdf-summary.md | Adds ### Output Format guidance. |
| .github/workflows/pdf-summary.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/org-health-report.md | Adds ### Output Format guidance. |
| .github/workflows/org-health-report.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/example-workflow-analyzer.md | Adds ### Output Format guidance. |
| .github/workflows/example-workflow-analyzer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-yamllint-fixer.md | Adds ### Output Format guidance. |
| .github/workflows/daily-yamllint-fixer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-workflow-updater.md | Adds ### Output Format guidance. |
| .github/workflows/daily-workflow-updater.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-team-evolution-insights.md | Adds ### Output Format guidance. |
| .github/workflows/daily-team-evolution-insights.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-syntax-error-quality.md | Adds ### Output Format guidance. |
| .github/workflows/daily-syntax-error-quality.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-skill-optimizer.md | Adds ### Output Format guidance. |
| .github/workflows/daily-skill-optimizer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-semgrep-scan.md | Adds ### Output Format guidance. |
| .github/workflows/daily-semgrep-scan.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-security-observability.md | Adds ### Output Format guidance. |
| .github/workflows/daily-security-observability.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-safeoutputs-git-simulator.md | Adds ### Output Format guidance. |
| .github/workflows/daily-safeoutputs-git-simulator.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-safe-output-integrator.md | Adds ### Output Format guidance. |
| .github/workflows/daily-safe-output-integrator.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-rendering-scripts-verifier.md | Adds ### Output Format guidance. |
| .github/workflows/daily-rendering-scripts-verifier.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-multi-device-docs-tester.md | Adds ### Output Format guidance. |
| .github/workflows/daily-multi-device-docs-tester.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-model-inventory.md | Adds ### Output Format guidance. |
| .github/workflows/daily-model-inventory.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-malicious-code-scan.md | Adds ### Output Format guidance. |
| .github/workflows/daily-malicious-code-scan.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-hippo-learn.md | Adds ### Output Format guidance. |
| .github/workflows/daily-hippo-learn.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-geo-optimizer.md | Adds ### Output Format guidance. |
| .github/workflows/daily-geo-optimizer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-function-namer.md | Adds ### Output Format guidance. |
| .github/workflows/daily-function-namer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-experiment-report.md | Adds ### Output Format guidance. |
| .github/workflows/daily-experiment-report.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-doc-updater.md | Adds ### Output Format guidance. |
| .github/workflows/daily-doc-updater.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-doc-healer.md | Adds ### Output Format guidance. |
| .github/workflows/daily-doc-healer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-compiler-threat-spec-optimizer.md | Adds ### Output Format guidance. |
| .github/workflows/daily-compiler-threat-spec-optimizer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-community-attribution.md | Adds ### Output Format guidance. |
| .github/workflows/daily-community-attribution.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-choice-test.md | Adds ### Output Format guidance. |
| .github/workflows/daily-choice-test.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-caveman-optimizer.md | Adds ### Output Format guidance. |
| .github/workflows/daily-caveman-optimizer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-astrostylelite-markdown-spellcheck.md | Adds ### Output Format guidance. |
| .github/workflows/daily-astrostylelite-markdown-spellcheck.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/daily-ambient-context-optimizer.md | Adds ### Output Format guidance. |
| .github/workflows/daily-ambient-context-optimizer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/commit-changes-analyzer.md | Adds ### Output Format guidance. |
| .github/workflows/commit-changes-analyzer.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/blog-auditor.md | Adds ### Output Format guidance. |
| .github/workflows/blog-auditor.lock.yml | Regenerated lock metadata for workflow body change. |
| .github/workflows/agentic-token-trend-audit.md | Adds ### Output Format guidance. |
| .github/workflows/agentic-token-trend-audit.lock.yml | Regenerated lock metadata for workflow body change. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 72/72 changed files
- Comments generated: 3
- Review effort level: Low
| ### Output Format | ||
|
|
||
| Structure reports as: overview → key metrics/issues → collapsible detail → next actions. |
| ### Output Format | ||
|
|
||
| Wrap long content with `<details><summary><b>View Details</b></summary>...</details>`. |
There was a problem hiding this comment.
Review: Normalize report formatting for 36 workflows
Overall: Approved — clean, additive-only, targeted changes
This PR adds a ### Output Format section to 36 workflow .md files to enforce consistent report structure. The changes are surgical and correct.
Findings:
| Category | Count | Status |
|---|---|---|
Files with ### Output Format added |
36 | ✅ Correct |
| Files with newline-at-EOF fixes | 5 | ✅ Correct |
| Lock file body_hash updates | 36 | ✅ Consistent |
| Upstream-managed file excluded | 1 | ✅ Correct exclusion |
| Content removed from existing sections | 0 | ✅ No regressions |
Each ### Output Format section uses the correct header level, contains only missing elements per the PR description, is placed before {{#runtime-import shared/noop-reminder.md}} or at EOF, and excludes upstream-managed workflows. No issues found.
🧵 Reviewed using Impeccable skills by Impeccable Skills Reviewer · 43 AIC · ⌖ 6.01 AIC · ⊞ 4.9K
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs and /codebase-design — requesting changes on two correctness issues (one blocking) and two consistency issues.
📋 Key Themes & Highlights
Key Issues
- 🚨
daily-malicious-code-scan.md—### Output Formatplaced inside a sub-agent block (threat-scorer) that mandatesReturn JSON only. The section should move to the end of the file where it applies to the top-level agent. - 🔁 DRY violation — the 36 inlined
### Output Formatblocks duplicate content already present inshared/reporting.md. Using{{#runtime-import shared/reporting.md}}would keep guidance canonical and reduce future update burden. - 🎯 Semantic mismatch —
daily-choice-test.mdis a single-tool-call test harness, not a report workflow; theStructure reports as: overview → key metrics...directive does not apply. - 📝 Double blank lines — ~12 files have two consecutive blank lines before
### Output Format, a minor cosmetic inconsistency worth cleaning up.
Positive Highlights
- ✅ Good discipline in excluding
agentic-token-audit.md(upstream-managed) - ✅ Targeted additions — only missing elements were added, existing output sections were not touched
- ✅ Consistent heading level (
###) throughout all additions - ✅ Correct placement relative to
{{#runtime-import shared/noop-reminder.md}}in most files
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 111.3 AIC · ⌖ 5.48 AIC · ⊞ 6.6K
Comment /matt to run again
|
|
||
| Return JSON only: `{"score":<int>,"severity":"error|warning|note","rationale":"<one sentence>"}`. Do not add extra fields. | ||
|
|
||
| ### Output Format |
There was a problem hiding this comment.
[/grill-with-docs] The ### Output Format section is placed inside the threat-scorer agent sub-block (which begins at line 341), creating a direct contradiction with the preceding Return JSON only: {...}. Do not add extra fields. instruction.
💡 Why this matters
The threat-scorer agent is a sub-agent that emits a single JSON object to be consumed by the orchestrator — not a human-readable report. Adding <details> wrapping guidance is nonsensical there and may confuse the model.
The ### Output Format section should be appended after the final ## agent: block (i.e., at the very end of the file or before {{#runtime-import shared/noop-reminder.md}}), where it applies to the top-level workflow agent that produces the user-facing report — not to the inner threat-scorer sub-agent.
@copilot please address this.
| - **Respect excluded files**: Never touch the excluded list above. | ||
|
|
||
|
|
||
| ### Output Format |
There was a problem hiding this comment.
[/codebase-design] The inlined ### Output Format directives are a verbatim subset of shared/reporting.md, which already consolidates all three rules (h3-only headers, report structure, and <details> wrapping). Adding 36 copies of the same prose creates a maintenance surface — when the canonical guidance changes, each copy needs updating independently.
💡 Suggested alternative
Replace the inlined block with a single {{#runtime-import shared/reporting.md}} import (following the same pattern used for noop-reminder.md). This keeps workflows DRY and ensures they pick up any future refinements to the shared guidance automatically.
If only a subset of the three directives applies to a given workflow, consider adding targeted subsection imports or a filtered variant of shared/reporting.md rather than duplicating prose.
@copilot please address this.
| Provide a brief explanation of why you chose this configuration. | ||
|
|
||
|
|
||
| ### Output Format |
There was a problem hiding this comment.
[/grill-with-docs] The Structure reports as: overview → key metrics/issues → collapsible detail → next actions directive is semantically mismatched with this workflow, which calls test_environment and provides a brief explanation of its selection — not a multi-section report with metrics or collapsible detail.
💡 Suggestion
Remove the structure-report directive and keep only the <details> wrapping guidance, which is genuinely applicable if the explanation grows. Alternatively, simplify the Output Format to just: Keep your explanation concise — one or two sentences is sufficient.
Applying generic report-structure guidance uniformly across all workflow types (including simple tool-call tests) dilutes its signal where it matters.
@copilot please address this.
| Begin your audit now. Navigate to the blog using Playwright, capture the accessibility snapshot, extract and validate code snippets, validate all criteria, and report your findings. | ||
| {{/if}} | ||
|
|
||
|
|
There was a problem hiding this comment.
[/codebase-design] There is an extra blank line before ### Output Format (two consecutive blank lines between {{/if}} and the heading). This occurs in at least 12 of the 36 modified files.
💡 Detail
Markdown convention is a single blank line between sections. The double blank is a minor cosmetic inconsistency but it does appear in the compiled .lock.yml prompt and could make workflows slightly harder to read at a glance.
Affected files include: blog-auditor.md, commit-changes-analyzer.md, daily-caveman-optimizer.md, daily-choice-test.md, daily-compiler-threat-spec-optimizer.md, and others. A follow-up pass to normalise these would be worthwhile.
@copilot please address this.
There was a problem hiding this comment.
REQUEST_CHANGES — normalization script applied directives without validating workflow semantics, introducing two correctness bugs and two incomplete sections.
Blocking issues
**1. ** — config-picker workflow incorrectly instructed to "Structure reports". The workflow outputs a one-sentence explanation, not a report. Adding a multi-section report template will cause the agent to produce unrequested structured output.
**2. ** — the appended Structure reports as directive directly contradicts the existing explicit issue-body template (lines 207–226). Two competing structural contracts create non-deterministic output formatting.
Non-blocking but should fix
3. daily-semgrep-scan.md — the Output Format block is missing the Structure reports as directive; it's the only scan-report workflow in the batch that didn't get it.
4. blog-auditor.md — produces a full audit discussion but received only the <details> wrap guidance; both the structure directive and the header-level constraint are absent.
Dropped items (low signal, out of scope for blocking)
- Double blank lines before
### Output Formatindaily-caveman-optimizer.mdanddaily-choice-test.md— cosmetic inconsistency from the normalization script. daily-hippo-learn.md/daily-multi-device-docs-tester.mdpartial sections — low risk.ubuntu-image-analyzer.mdmissing newline at EOF — confirmed the original also lacked a trailing newline; not a regression.
🔎 Code quality review by PR Code Quality Reviewer · 140.1 AIC · ⌖ 6.1 AIC · ⊞ 5.4K
Comment /review to run again
|
|
||
| ### Output Format | ||
|
|
||
| Structure reports as: overview → key metrics/issues → collapsible detail → next actions. |
There was a problem hiding this comment.
Semantically wrong directive for a config-picker workflow: daily-choice-test selects a CI environment and test type, not a report — adding Structure reports as: overview → key metrics/issues... will mislead the agent into producing an unrequested structured report instead of a brief configuration explanation.
💡 Suggested fix
Either remove the Structure reports as line entirely, or replace it with guidance appropriate to the actual output — a brief one-sentence explanation of the chosen configuration:
### Output Format
Respond with a single short paragraph explaining the chosen environment, test type, and the day-based rationale.The Structure reports as: overview → key metrics/issues → collapsible detail → next actions template is designed for multi-section diagnostic reports, not a one-sentence configuration choice. The existing workflow body already specifies "Provide a brief explanation of why you chose this configuration."
|
|
||
| ### Output Format | ||
|
|
||
| Structure reports as: overview → key metrics/issues → collapsible detail → next actions. |
There was a problem hiding this comment.
Conflicting output format contracts: the workflow already defines a strict Markdown template for the issue body at lines 207–226 (Summary / Key Findings in a <details> block / Recommendations). Appending a second Structure reports as: overview → key metrics/issues → collapsible detail → next actions contract introduces an ambiguous, contradictory instruction — the agent will have two competing layout schemas and may non-deterministically follow either one.
💡 Suggested fix
The explicit template already embedded in the workflow body is the authoritative contract. Remove the appended Structure reports as line to avoid contradicting it. If the <details> wrap guidance is missing from the existing template, add it there inline instead:
### Output Format
Use `###` (or lower) headers only. The issue body template above is authoritative — do not deviate from it.Adding a generic report-structure directive after a precise per-field template will cause drift in issue formatting across runs.
|
|
||
| ### Output Format | ||
|
|
||
| Use `###` (or lower) headers only. |
There was a problem hiding this comment.
Incomplete Output Format section — missing Structure reports as directive: semgrep produces a security findings narrative report or code-scanning alerts, yet its Output Format block only got the header-level constraint (Use ### or lower headers only) and the <details> wrap guidance. The structure directive present in all comparable scan/report workflows (Structure reports as: overview → key metrics/issues → collapsible detail → next actions) was omitted.
💡 Suggested fix
Add the missing structure directive so the full block is consistent with the other scan workflows in this PR:
### Output Format
Use `###` (or lower) headers only.
Structure reports as: overview → key metrics/issues → collapsible detail → next actions.
Wrap long content with `<details><summary><b>View Details</b></summary>...</details>`.Without the structure directive, the semgrep agent has no guidance on how to organise its narrative security assessment relative to other scan reports — an inconsistency introduced by this normalization PR.
|
|
||
| ### Output Format | ||
|
|
||
| Wrap long content with `<details><summary><b>View Details</b></summary>...</details>`. |
There was a problem hiding this comment.
Incomplete Output Format section for a full-audit-report workflow: blog-auditor produces a comprehensive accessibility + code-snippet validation audit posted as a GitHub discussion, yet its Output Format block only received the <details> wrap guidance. Both the Structure reports as: overview → key metrics/issues... directive and the Use ### or lower headers only constraint (present in other audit-style workflows like daily-semgrep-scan) were omitted, leaving this the least-guided report-producing workflow in the batch.
💡 Suggested fix
### Output Format
Use `###` (or lower) headers only.
Structure reports as: overview → key metrics/issues → collapsible detail → next actions.
Wrap long content with `<details><summary><b>View Details</b></summary>...</details>`.The blog-auditor discussion body is lengthy and benefits most from structure guidance. Omitting both directives while applying <details> wrap alone is inconsistent with the stated goal of this PR.
|
@copilot please run the
|
Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com>
Addressed the workflow prompt follow-ups in a73c9c0. I fixed the JSON-only/output-contract conflicts, tightened the mismatched report-format guidance, completed the missing report-format sections, recompiled the affected lockfiles, and confirmed the branch is not behind |
🤖 PR Triage — Run §28741077056
Rationale: Bulk style normalization across 36 workflow files. github-actions bot has CHANGES_REQUESTED. Resolve bot review concerns before re-triaging. Low urgency — acceptable to hold until bot feedback is addressed.
|
|
@copilot please run the Unresolved review feedback to address:
|
Automated style scan identified 37 workflows missing one or more of: h3+ header guidance,
<details>progressive disclosure instructions, and explicit report structure guidance. Adds a### Output Formatsection to each non-compliant workflow with only the specific missing elements.Changes
.mdfiles — each receives a### Output Formatsection appended before{{#runtime-import shared/noop-reminder.md}}(or at EOF) containing the subset of missing directives:agentic-token-audit.mdexcluded — upstream-managed (source: githubnext/agentic-ops@...); must be updated viagh aw update.