validate-report-file
Validate that worker-generated reports have all required sections and proper formatting. Use in quality gates, for report completeness checking, or when debugging missing report sections.
When & Why to Use This Skill
This Claude skill automates the validation of agent-generated reports, ensuring they adhere to specific structural requirements and formatting standards. It acts as a robust quality gate by verifying essential sections (like Executive Summaries and Validation Results), checking Markdown syntax, and ensuring internal status consistency to maintain high-quality, professional documentation.
Use Cases
- Automated Quality Gates: Implement a mandatory validation step in agentic workflows to ensure all generated reports meet professional standards before human review or delivery.
- Debugging Agent Failures: Quickly identify missing sections or structural errors in reports generated by sub-agents to pinpoint logic flaws in the generation process.
- Documentation Consistency: Enforce a unified structure across various report types, ensuring mandatory metadata, headers, and status indicators are present and correctly formatted.
- Status Alignment Verification: Programmatically check that report status indicators (e.g., success/failure emojis) consistently match the actual validation results within the document body.
| name | validate-report-file |
|---|---|
| description | Validate that worker-generated reports have all required sections and proper formatting. Use in quality gates, for report completeness checking, or when debugging missing report sections. |
| allowed-tools | Read |
Validate Report File
Validate agent-generated report files for completeness and proper structure.
When to Use
- Quality gate validation after worker completion
- Debugging missing report sections
- Ensuring report consistency
- Pre-submission validation
Instructions
Step 1: Read Report File
Use Read tool to load report file.
Expected Input:
file_path: Path to report file (e.g.,bug-hunting-report.md)
Tools Used: Read
Step 2: Check Required Sections
Verify all required sections are present.
Required Sections:
Header with metadata:
- Title (# Report Type Report: Version)
- Generated timestamp
- Status indicator (✅/⚠️/❌)
- Version identifier
Executive Summary:
Executive Summary heading
- Key metrics and findings
Detailed Findings:
- Varies by report type
- Must have at least one detail section
Validation Results:
Validation Results heading
- Build/type-check status
- Overall validation status
Next Steps:
Next Steps heading
- Action items or recommendations
Step 3: Validate Format
Check formatting and structure.
Format Rules:
- Title must be H1 (single #)
- Section headers must be H2 (##)
- Status must include emoji (✅/⚠️/❌)
- Code blocks must use proper markdown
- Lists must be properly formatted
Step 4: Check Status Consistency
Verify status indicators are consistent.
Consistency Checks:
- Header status matches validation status
- If status is "failed", validation should show failures
- If status is "success", validation should show passes
Step 5: Return Validation Result
Return detailed validation result.
Expected Output:
{
"valid": true,
"file": "bug-hunting-report.md",
"sections": {
"header": true,
"executiveSummary": true,
"detailedFindings": true,
"validationResults": true,
"nextSteps": true
},
"warnings": [],
"errors": []
}
Error Handling
- File Not Found: Return error with file path
- Missing Sections: List all missing required sections
- Invalid Format: Describe format issues
- Inconsistent Status: Warn about status mismatches
Examples
Example 1: Valid Report
Input:
file_path: bug-hunting-report.md
File Content:
# Bug Hunting Report: 2025-10-17
**Generated**: 2025-10-17 14:30:00 UTC
**Status**: ✅ success
---
## Executive Summary
Found 23 bugs across 147 files.
## Detailed Findings
### Critical (3)
- Bug 1
- Bug 2
- Bug 3
## Validation Results
- Type-check: ✅ PASSED
- Build: ✅ PASSED
**Overall**: ✅ PASSED
## Next Steps
1. Review critical bugs
2. Schedule fixes
Output:
{
"valid": true,
"file": "bug-hunting-report.md",
"sections": {
"header": true,
"executiveSummary": true,
"detailedFindings": true,
"validationResults": true,
"nextSteps": true
},
"warnings": [],
"errors": []
}
Example 2: Missing Sections
Input:
file_path: incomplete-report.md
File Content:
# Bug Report
Some bugs found.
Output:
{
"valid": false,
"file": "incomplete-report.md",
"sections": {
"header": false,
"executiveSummary": false,
"detailedFindings": false,
"validationResults": false,
"nextSteps": false
},
"warnings": [],
"errors": [
"Missing header metadata (Generated, Status, Version)",
"Missing section: Executive Summary",
"Missing section: Detailed Findings",
"Missing section: Validation Results",
"Missing section: Next Steps"
]
}
Example 3: Inconsistent Status
Input:
file_path: inconsistent-report.md
File Content:
# Bug Report: 2025-10-17
**Status**: ✅ success
## Executive Summary
Failed to scan files.
## Validation Results
**Overall**: ❌ FAILED
Output:
{
"valid": false,
"file": "inconsistent-report.md",
"sections": {
"header": true,
"executiveSummary": true,
"detailedFindings": false,
"validationResults": true,
"nextSteps": false
},
"warnings": [
"Status inconsistency: Header shows success (✅) but validation shows failed (❌)"
],
"errors": [
"Missing section: Detailed Findings",
"Missing section: Next Steps"
]
}
Validation
- Checks all required sections present
- Validates header metadata
- Verifies status consistency
- Detects format issues
- Returns clear error messages
- Handles missing files gracefully
Supporting Files
schema.json: Report structure schema (see Supporting Files section)