Build Coverage Gap Report
1. Gather Inputs
- Require the current
docs/testing/test-mapping-report.md. - Require
docs/testing/contract-mismatches.mdwhen it exists. - Require the active coverage matrices when they contain gaps not yet reflected in traceability.
2. Choose The Files
- Prefer
docs/testing/coverage-gap-report.md. - When the user wants human-friendly navigation, also generate
docs/testing/html/coverage-gap-report.html.
3. Build The Report
- Treat
Not covered,Partial, andContract driftoperations as primary gaps. - Include explicit gap bullets from the traceability report.
- Separate the report into summary, operation gaps, and planning recommendations.
- Keep one operation row per endpoint and method in markdown.
- In HTML, group the operation gaps by resource and make the next action obvious.
4. Output Shape
- Start from coverage-gap-report-template.md.
- Keep the exact section headings so the generator can update the file deterministically.
- Run
python scripts/generate_coverage_gap_report.py --mapping <mapping-md> --output-md <gap-md> --output-html <gap-html>.
5. Keep It Actionable
- Explain why each gap matters.
- Recommend the next slice to implement.
- Update the session-state artifact after generating or changing the report.
6. Examples
- Input:
Show me the biggest API coverage gaps.Output: Createdocs/testing/coverage-gap-report.mdand the paired HTML report. - Input:
Which endpoints are only covered through drift assertions?Output: Produce a gap report that isolatesContract driftoperations and suggests next actions.
7. Troubleshooting
- Problem: The traceability report says everything is covered.
Fix: Still surface
Contract driftrows and explicit gap bullets because those are planning gaps. - Problem: The markdown and HTML disagree. Fix: Regenerate the HTML from the canonical markdown inputs and do not hand-edit the HTML.