compat-hunter

name	compat-hunter
description	Use when hunting for OBJ/GLB/glTF/VOX parser compatibility issues by streaming candidate models, parsing each immediately, deleting clean files, and retaining only actionable failures, unknown warnings, or unexplained zero-polygon outputs. Especially useful in the polycss repo with scripts/compat-hunter.mjs.

Compat Hunter

Use this skill when the user wants to keep digging for parser compatibility issues without building a fixed local corpus.

Workflow

1. In the repo, prefer the reusable script:

   pnpm compat-hunter -- --max-models 2000
   

   Equivalent explicit form:

   pnpm --filter @layoutit/polycss-core build
   node .agents/skills/compat-hunter/scripts/compat-hunter.mjs --max-models 2000
   

2. Let the script stream remote OBJ/GLB/glTF/VOX candidates, parse each model, and discard clean files. Reports are written under bench/results/, which is ignored by git.

3. Treat these as known non-actionable unless the user asks to support them:

   • glTF POINTS/LINES/LINE_LOOP/LINE_STRIP primitives.
   • Required Draco or meshopt compressed primitives skipped with a warning.

4. Stop and inspect anything classified as:

   • throw
   • unknown-warning
   • obj-zero-no-warning
   • glb-zero-no-warning

5. If an actionable parser issue is found, keep the saved file under the report's interesting/ directory, add a focused parser test using that behavior, implement the smallest fix, and rerun the focused parser tests plus the hunter on the saved file or source class.

Useful Commands

Fresh Objaverse and expanded GitHub stream:

pnpm compat-hunter -- --max-models 5000 --max-bytes 10mb --timeout-ms 30000

Objaverse only, later shards:

pnpm compat-hunter -- --sources objaverse --objaverse-shards 120:220 --max-models 5000

GitHub only:

pnpm compat-hunter -- --sources github --max-models 500

Poly Haven only:

pnpm compat-hunter -- --sources polyhaven --polyhaven-limit 250 --max-models 200

VOX-heavy GitHub sources:

pnpm compat-hunter -- --sources github --github-repos ephtracy/voxel-model@master:vox/,mikelovesrobots/mmmm@master:vox/ --max-models 1000

Local directory:

pnpm compat-hunter -- --sources local --local-root /tmp/models --max-models 1000

Keep known-warning files too:

pnpm compat-hunter -- --keep-known --max-models 500

Continue after interesting cases:

pnpm compat-hunter -- --no-stop-on-interesting --max-models 2000

Reporting

Summarize the final report.json with:

pnpm compat-hunter -- --report bench/results/<run>/report.json

In the final response, state the attempted/parsed counts, whether any interesting files were retained, and whether the findings are actionable. Do not imply a clean stream proves full compatibility; it only means this pass found no new actionable parser issue.