Files
osmWorkflow/.trellis/tasks/archive/2026-08/08-04-add-area-diagnostics/prd.md

2.0 KiB

Add area diagnostics command

Goal

Add a fast area diagnostics CLI for OSM structure and existing output artifact health.

Requirements

  • Add a fast diagnostics CLI for an area config.
  • The command must not invoke QGIS, Blender, Cesium, or GLB compression.
  • The report must scan the configured OSM XML for common manual-edit risks: bounds presence, nodes, ways, relations, building ways, building multipolygon relations, explicit heights, building levels, malformed relation members, unresolved member ways, open rings, and basic vegetation counts.
  • The report must inspect existing output artifacts when present: GeoJSON directory, GeoPackage, QGIS project, .blend, render PNG, GLB, metadata, Cesium preview, compressed GLB, compressed metadata, and compressed preview.
  • If a GLB exists, the report should reuse the existing GLB digest logic to summarize size, nodes, meshes, materials, images, accessors, and extensions.
  • The command should emit clear warnings for likely trouble, including missing OSM bounds, malformed building multipolygons, missing expected artifacts, GLB over a conservative size budget, high node count, and high texture count.
  • Add an npm script and README usage.

Acceptance Criteria

  • npm run diagnose:area -- --config config/areas/nantaizi-lake-innovation-valley.json prints a useful text report without running heavy build stages.
  • The diagnostics report includes OSM structure, building relation health, vegetation counts, output artifact status, and GLB digest summary.
  • Missing optional output artifacts are warnings, not hard failures.
  • Syntax checks pass for the changed Node scripts.
  • README documents the new diagnostic command.

Notes

  • Keep prd.md focused on requirements, constraints, and acceptance criteria.
  • Lightweight tasks can remain PRD-only.
  • For complex tasks, add design.md for technical design and implement.md for execution planning before task.py start.