[workflow-style] Normalize report formatting for bot-detection

[github-actions]

Workflow to Update

Workflow File: .github/workflows/bot-detection.md
Issue: This workflow generates security reports but doesn't include markdown style guidelines

Recent Activity: This workflow was active in the last 24 hours, triggering on issue/PR events to analyze suspicious accounts.

Required Changes

Update the workflow prompt to include these formatting guidelines:

1. Header Levels

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

Current problem: The workflow creates issues with security reports but doesn't specify header levels, which may result in inconsistent formatting.

2. Progressive Disclosure

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

Example:

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

[Detailed red flag evidence, timestamps, code snippets...]

</details>

Specific recommendations for bot-detection reports:

• Keep critical information visible: Risk score, risk level, primary red flags
• Collapse detailed evidence into <details> sections:
  • Per-red-flag evidence breakdowns
  • Complete account profile data
  • Detailed code analysis or network traces
  • Historical activity logs

3. Report Structure

Suggest a structure like:

• Brief Summary (always visible): Risk level, risk score, detection context
• Key Red Flags (always visible): Top 2-3 concerns that triggered detection
• Detailed Evidence (in <details> tags): Per-red-flag breakdowns with timestamps
• Account Profile (in <details> tags): Complete profile data
• Recommendation (always visible): Next steps for human reviewers

Design Principles (Airbnb-Inspired)

The updated workflow should create reports that:

1. Build trust through clarity: Most important security info (risk level, key red flags) immediately visible
2. Exceed expectations: Add helpful context about account patterns, comparison to known bot behaviors
3. Create delight: Use progressive disclosure to present dense security data without overwhelming reviewers
4. Maintain consistency: Follow the same patterns as other security reporting workflows

Implementation Options

Option 1: Add inline formatting guidelines (quick fix)
Add a "Report Formatting Guidelines" section to the workflow prompt with the specific instructions above.

Option 2: Import shared/reporting.md (recommended)
Add to the workflow frontmatter:

imports:
  - shared/reporting.md

This imports centralized formatting guidelines that are consistent across all reporting workflows.

Example Reference

See workflows like daily-firewall-report or security-compliance for good examples of structured security reporting with progressive disclosure.

Agent Task

Update the workflow file .github/workflows/bot-detection.md to include formatting guidelines. Ensure the bot detection reports:

• Use h3+ headers
• Collapse detailed evidence in <details> tags
• Keep critical security information visible
• Follow the report structure pattern above

Test the updated workflow by triggering it manually to ensure it produces well-formatted security reports.

AI generated by Workflow Normalizer

• expires on Feb 13, 2026, 3:33 AM UTC