geointel/docs/superpowers/plans/2026-07-11-yolo-label-qa-contact-sheets.md

YOLO Label QA Contact Sheets Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build an operator-only visual QA script that creates deterministic contact-sheet PNG artifacts from existing YOLO tile datasets.

Architecture: Add a standalone script under scripts/ with no backend/API/database changes. The script reads yolo_tile_dataset_summary.json, resolves image and label paths, selects a bounded deterministic tile subset, draws normalized YOLO labels using Pillow, and writes JSON/Markdown/PNG artifacts.

Tech Stack: Python standard library, Pillow, pytest subprocess-based script tests.

---

Task 1: Regression Test

Files:

• Create: backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py

• Write a failing test that creates a tiny YOLO dataset with train/val images, valid labels, an invalid label row and a missing label path.

• Run python -m pytest backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q.

• Expected result: failure because scripts/render_operator_yolo_label_qa_contact_sheets.py does not exist.

Task 2: Script Implementation

Files:

• Create: scripts/render_operator_yolo_label_qa_contact_sheets.py

• Implement CLI arguments:

  • --summary-path
  • --output-dir
  • --max-tiles
  • --columns
  • --thumb-size

• Implement summary loading and /app/... path resolution consistent with existing operator scripts.

• Implement YOLO label parsing with invalid/missing counts.

• Implement deterministic tile selection.

• Implement Pillow rendering to PNG contact sheets.

• Implement JSON and Markdown reports.

• Run the targeted test and keep the implementation minimal until it passes.

Task 3: Documentation

Files:

• Modify: scripts/README.md

• Modify: docs/TODO.md

• Modify: docs/CODEX_EXECUTION_LOG.md

• Document the command and intended usage.

• Mark visual contact sheets as implemented in TODO.

• Record local and Tower validation evidence.

Task 4: Verification And Deploy

Commands:

• python -m pytest backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q

• python -m pytest backend/tests/test_sprint146_operator_yolo_dataset_quality_audit.py backend/tests/test_sprint167_operator_yolo_label_qa_contact_sheets.py -q

• bash scripts/run_readiness_check.sh

• powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy_tower.ps1

• Tower script run against /app/storage/operator-data/yolo-building-aoi1024-cleanpx12vis035/yolo_tile_dataset_summary.json

• Commit and push after local readiness.

• Redeploy Tower.

• Generate Tower contact sheets.

• Commit and push evidence docs.