docs(skills): add choosing-a-visualization agent skill

[mikemcdougall]

Summary

Starts an agent-skills corpus in this standard repo: encoded cartographic
judgment for agents driving a geospatial-mcp-conformant server. The MCP surface
says what tools exist; this corpus says what a good result looks like — the
judgment a correctly-formed tool call still doesn't supply. Skills are
client-side context; they add no tools and change no server behavior.

The corpus is written against the standard vocabulary (tool families,
canonical objects, workflow families in spec/taxonomy.md), not any one
server's tool names, so it is portable to any conformant implementation and
Apache-2.0-licensed like the rest of the repo.

First slice — one skill, deliberately

Per the tracking issue's split guidance, this ships a single skill rather
than a broad corpus. choosing-a-visualization is first because it is where an
unguided model most reliably renders something clean and still misleading.

The skill covers, with an explicit trigger condition ("use this when…"):

• Variable type → palette family + scale type — nominal / ordinal /
  sequential / diverging / cyclic, each mapped to a palette family and scale.
• When a choropleth is the wrong map — raw counts on unequal areas, MAUP,
  non-areal geometry, with honest alternatives (graduated symbols, dot density).
• Classification method selection and failure modes — equal interval,
  quantile, Jenks, standard deviation, manual, head/tail, unclassed; where each
  lies; comparability across small multiples.
• Anti-patterns — the highest-signal section: 12 named wrong outputs a tool
  call produces without complaint (sequential ramp on nominal data, choropleth
  of raw counts, diverging palette with no midpoint, rainbow ramps, quantile-as-
  magnitude, linear ramp on cyclic data, and more).
• A worked Maui parcel example as the intended cold-model validation
  substrate.

Mapping to the standard

Decisions feed the map-composition surface: RendererSpec, StyleRef (via
apply_style_preset), create_map_package / refine_map_package, and
reference-shape render_map, in the Analyze and Build App families. Nothing
mutates data — symbology is presentation metadata, consistent with the non-goals.

Changes

• Add skills/choosing-a-visualization/SKILL.md — the skill (frontmatter with
  trigger, decision rubric, choropleth disqualifiers, classification methods,
  anti-patterns, worked example, pre-flight checklist).
• Add skills/README.md — corpus intent, licensing, standard mapping, and the
  deferred follow-on slices (layer composition, query shaping, publishing).

Scope / non-goals

• No schema, index.json, conformance-fixture, or vocabulary changes — this is
  an additive skills/ tree, so no ADR is required.
• Does not copy CARTO's corpus; read only for shape.

Checks

• python3 tools/check_links.py — all internal relative links and anchors
  resolve.
• markdownlint-cli2 — clean on both new files.

Refs honua-io/honua-server#2858

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dd73b03ff4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Don't rule out valid choropleths for non-rate attributes

When mapping per-feature polygon attributes such as assessed value, this rule tells the agent that only a normalized rate/ratio may proceed to a choropleth, but the worked Maui example later treats assessed_value as valid because it is not a count and the parcel units are meaningful. For non-count polygon attributes this will push agents to reject or over-normalize valid polygon fills; the disqualifier should target raw counts on unequal/arbitrary units rather than all non-rate attributes.

Useful? React with 👍 / 👎.