Reporting Workflow

Reporting Workflow

When to Use

Use this skill when a task follows the common pattern:

1. inspect the input data/model/output expectations
2. run a report generator
3. open or validate the generated artifact
4. run targeted tests
5. refine the report if structure, visuals, or data mappings are wrong

Typical cases:

• benchmark reports
• engineering summary reports
• interactive HTML dashboards
• validation reports with plots/tables

Core Workflow

1. Inspect Inputs and Existing Patterns

Read the generator, input schema, and one known-good output first.

# inspect generator and fixtures
rg -n "report|dashboard|html" examples/ tests/ scripts/

Check for:

• required inputs and file locations
• expected output paths
• linked assets (plots, CSS, JS, images)
• existing tests or snapshots

2. Generate the Report

Run the narrowest generator command possible.

# generic pattern
uv run --no-project python path/to/generator.py

# if shell wrapper exists
bash path/to/generate-report.sh

Capture:

• output file path
• warnings/errors
• whether the file was regenerated or unchanged

3. Verify the Artifact

For HTML outputs, use structural + visual verification.

Preferred checks:

• file exists and is non-empty
• expected headings/sections are present
• expected charts/tables rendered
• no obvious console/JS failures

If the output is HTML, pair with:

• html-report-verify

4. Run Report-Focused Tests

Use the smallest test slice that covers the report workflow.

uv run pytest tests/reporting/ -q
# or a targeted file/case
uv run pytest tests/path/test_report_x.py::test_generates_expected_sections -q

If no report test exists yet:

• add a focused regression test for the bug or missing section
• prefer structural assertions over brittle full-file diffs unless snapshots are already standard

5. Iterate on Generator / Template / Data Mapping

Common failure buckets:

• wrong data aggregation
• missing section wiring
• broken template variables
• invalid asset paths
• JS/chart rendering failures
• report generated but not linked into navigation/index pages

Fix one layer at a time:

• data extraction
• transformation
• template rendering
• final asset packaging

6. Re-run Validation

After each fix:

• regenerate
• re-run targeted tests
• re-verify final artifact

Do not stop at “generator exited 0” — confirm the report is actually correct.

Recommended Validation Ladder

1. script exits successfully
2. output file exists
3. structural assertions pass
4. targeted tests pass
5. visual/HTML verification passes when relevant

Test Integration Guidance

Prefer tests that assert:

• key section headings exist
• expected records/counts appear
• chart containers exist
• critical summary metrics match fixture inputs

Avoid overly fragile tests that fail on harmless formatting changes unless snapshot testing is already expected.

Integration Notes

This skill complements:

• html-report-verify for visual/DOM verification
• interactive-report-generator for richer dashboard/report generation patterns
• engineering-report-generator for engineering-specific outputs

Common Pitfalls

• regenerating without checking the output path
• trusting console-clean output without opening the report
• testing only generator internals instead of final artifact structure
• mixing data bugs and template bugs in one change
• forgetting to add regression coverage for a discovered report bug