Skip to content

Seed batch mapping reports: tooling asks and batch findings #15

Description

@chiplay

The eight seed entries (#7#14) each shipped a summary.md inside entries/<slug>/ — an authoring report addressed to the sightmap team. The entry directory is the published artifact and docs/SPEC.md defines its layout, so the review pass moved those files out of the entries. Full text of all eight is preserved on the reports/seed-batch-2026-08 branch.

The asks that recur across the batch, so they don't get lost in eight separate files:

Tooling (sightmap CLI)

  1. Lint rule for the two YAML prose traps — a scalar starting with a reserved indicator, and a scalar containing ": ". Broke the build five times across eight entries, always with an error naming a line and never a cause. Both statically detectable. The batch report calls this the single highest-value change.
  2. Document the offline matcher's supported selector syntax. Two divergences surfaced ([action=...], the ~ combinator), each costing a debugging round because coverage reports the component as simply not matching. Confirmed working: id, class, tag, role, name, type, data-*, [attr^=], [attr$=], [attr*=], :not(), descendant, child, selector lists.
  3. Coverage should report the matched route, not just the view name — and warn when a view's own example URL resolves to a different view. Apple's /:productSlug marketing route swallowed the 404 probe and reported it as ProductMarketing with 92 orphans, which reads as "selectors wrong" rather than "routes overlap."
  4. Schema gap: requests that belong to a component, not a view or the file root. IKEA's per-card carousel fragment fetch fires on three views but belongs to the carousel; eBay's search stack serves two views. Today the only encoding is duplication per view, indistinguishable from unrelated endpoints. Same shape as the shells proposal.

Authoring skill

  1. 404 probe paths must not collide with locale or route segments. /no/such/page begins with Norway's country code and returns Norwegian on apple.com. Recommend something like /zz-sightmap-probe-404.
  2. Clear the network buffer between navigations (record the highest request index before navigating, drop everything at or below it) — the first IKEA capture filed product-page fetches under search.
  3. "Server-rendered" and "has no API" both need evidence — fetch with no JS and count real occurrences; grep -c on minified HTML undercounts catastrophically.
  4. Anything seen once is conditional until a second visit confirms it — eBay's below-results carousel fired on one visit and not the next, with identical DOM either way.

Worth knowing before the next seeding sprint

Of 22 well-known sites gated, 9 were usable. Rejected with distinct failure modes: Instacart (login modal over a full DOM), Home Depot (deep routes error), Target (never finishes loading), Best Buy (blank product pages, search stuck on skeletons). Only the third gate layer — deep routes plus a blocking-modal check — was reliable.

Every site in the batch has at least one way of failing silently (200 with wrong content, or right content with no confirmation signal). That's currently spread across memory: notes with nothing to query; a kind: hazard marker would let the CLI answer "what will silently mislead me here."

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions