(Line keyboard nav) Enhance S2 line features, reference lines, and documentation updates

.claude/commands/bug-summary.md

@@ -0,0 +1,44 @@
+# Bug Issue Summary
+
+Use when asked for a quick status scan of currently open bug issue specs (`/bug-summary`).
+Optional `$ARGUMENTS` narrows to a single `chartType` (e.g. `/bug-summary line`).
+
+## Step 1 — Collect open specs
+
+Find every `planning/specs/<chartType>/issues/*.json` file, excluding anything under an
+`implemented/` subdirectory — those are closed and out of scope for this summary. If
+`$ARGUMENTS` names a chartType, restrict to `planning/specs/<chartType>/issues/*.json` only.
+
+Sort the matched file paths ascending (plain string sort on the relative path, e.g.
+`planning/specs/bar/issues/foo.json` before `planning/specs/line/issues/bar.json`) and
+assign each a sequential id starting at 1, in that sorted order. This ordering must be
+reproducible on a later run over the same spec set — don't number by discovery order,
+read order, or complexity — so that a follow-up command given a bare id (e.g. "spec 3")
+can re-run this same collect-and-sort step to resolve which file it refers to.
+
+Consult `planning/specs/schema.json` if a field's meaning needs clarifying (e.g.
+`complexity.score`, `variant`, `crossCutting`).
+
+## Step 2 — Read each spec
+
+Read every matched file in full — don't rely on `summary`/`rootCause` alone if `symptom` or
+`comparison` adds context needed to describe the bug accurately.
+
+## Step 3 — Report
+
+Group output by `chartType`. For each issue, produce one bolded line followed by a tight
+2-4 sentence summary, in this exact shape:
+
+```
+**[N] `id`** (variant, complexity N) — one clause naming the symptom, then 1-3 sentences on
+the confirmed/suspected root cause and how settled the investigation is (e.g. "root cause
+unconfirmed, needs repro on main first" vs. "fully scoped, single-line fix").
+```
+
+`[N]` is the sequential id assigned in Step 1 (not the complexity score — the two numbers
+are unrelated and both appear on the line, so don't conflate them).
+
+Keep summaries compressed — this is a scan, not the full spec. Never print raw JSON or dump
+full spec fields. If nothing matches, say so plainly rather than returning an empty response.
+
+End with a one-line total, e.g. "5 open issues across bar, line, chart."

.claude/commands/file-issue.md

@@ -1,25 +1,87 @@
 # File a Bug Issue
 
-Use when a bug has been identified but won't be fixed immediately. Investigates the root cause
-and creates a structured issue doc in `planning/issues/`.
+Use when a bug has been identified but won't be fixed immediately. Investigates the root
+cause and writes a validated JSON `kind: "bug"` spec at
+`planning/specs/<chartType>/issues/<slug>.json`. The spec is submitted as a PR like any
+other; once merged, `implement-bug-fix` checks for it first (Step 0) and treats it as
+authoritative starting context instead of rediscovering the same investigation.
 
-## Steps
+Read `planning/specs/README.md` first (particularly "Kinds: feature vs bug" and the
+`crossCutting` table) and `planning/specs/schema.json` for the exact field contract.
 
-1. **Clarify scope** — confirm the symptom, affected mark/hook/util, and what correct behavior
-   looks like. Ask if unclear.
+Do not implement the fix as part of this skill — the goal is a clear, actionable record for
+later.
 
-2. **Investigate** — spawn an Explore subagent to:
-   - Find the relevant source files for the reported area
-   - Read the encoding/logic for the affected behavior
-   - Compare against similar working code (e.g. line mark vs. line points)
-   - Note exact file paths and line numbers where the divergence is
+---
 
-3. **Write the issue doc** to `planning/issues/<kebab-case-title>.md`:
-   - Status: Open
-   - Symptom: 1-2 sentences
-   - Root cause: technical, with file:line references
-   - Comparison table if applicable (what working code does vs. buggy code)
-   - Relevant files table
-   - Proposed fix direction (not implementation)
+## Step 1 — Clarify scope
 
-4. **Do not implement the fix.** The goal is a clear, actionable record for later.
+Confirm the symptom, the affected mark/hook/util, and what correct behavior looks like. Ask
+if unclear. Determine the `chartType` (`bar`, `line`, `donut`, `area`, `scatter`, `combo`,
+`bigNumber`, `bullet`, `venn`, or `chart` for a chart-level bug) — it determines the output
+directory.
+
+## Step 2 — Investigate
+
+Spawn an Explore subagent to:
+- Find the relevant source files for the reported area
+- Read the encoding/logic for the affected behavior
+- Compare against similar working code (e.g. line mark vs. line points, or the S2 sibling
+  file if one exists) — this comparison is what populates `comparison` and often reveals
+  the fix direction for free
+- Note exact file paths and line numbers where the divergence is, or where the behavior is
+  simply missing
+
+If the root cause can't be confirmed (e.g. a layout/rendering bug with only a hypothesis),
+say so plainly in `rootCause` rather than asserting a guess — use `openQuestions` for what's
+left to verify.
+
+Check whether the mark exists in both `vega-spec-builder` and `vega-spec-builder-s2` (or
+the corresponding React packages) — this determines `requiresS1S2Parity`. A bug found in one
+package doesn't automatically mean the other has it too; check directly, per the S2-parity
+rule in `implement-bug-fix.md` ("apply the same fix unless the bug doesn't exist in s2 —
+verify, don't assume").
+
+## Step 3 — Write the spec
+
+Fill out every required field from `schema.json`:
+
+- `id`, `title`, `chartType`, `kind: "bug"`, `summary`
+- `variant`: `"s1"`, `"s2"`, or `"both"` — whichever package variant(s) Step 2 confirmed the
+  bug actually reproduces in. Don't default to `"both"` just because the mark exists in
+  both packages — only use it once both have actually been checked. If only one has been
+  checked, use that one and leave an `openQuestions` entry for the other, or set
+  `crossCutting.requiresS1S2Parity: true` with a note.
+- `status`: `"approved"` (default — means filed/open for a bug; see README.md)
+- `lastUpdated`: run `date +%Y-%m-%d` in a shell and use its literal output — never your own
+  sense of the current date. See README.md's "Stamping lastUpdated."
+- `complexity`: score (`1|2|3|5`) + a one-line rationale, using the rubric in README.md —
+  score by how much the *fix* is expected to touch, not how hard the bug was to find
+- `symptom`: 1-2 sentences, the observable/user-facing behavior
+- `rootCause`: technical explanation with file:line references, from Step 2. If unconfirmed,
+  state the leading hypothesis and say it's unconfirmed
+- `comparison` (optional): populate when Step 2 found a clean working-vs-buggy contrast
+  (e.g. what a comparable mark's encoding does vs. what the buggy one does)
+- `crossCutting`: answer all six flags explicitly based on Step 2's exploration — never
+  leave a flag `false` without having actually checked it against the code. Add `notes` for
+  any flag that's `true`, and for `requiresS1S2Parity`, note whether the sibling package
+  already has correct behavior (a reference to port from) or reproduces the same bug
+- `implementationPlan`: one entry per file from Step 2. `change` describes the file's role
+  (bug location vs. reference) and a proposed fix *direction* — not a committed
+  implementation, since the fix hasn't been written
+- `openQuestions`: anything unresolved, especially unconfirmed root causes or unverified
+  S1/S2 parity
+
+Write the file to `planning/specs/<chartType>/issues/<slug>.json` — the base `issues/`
+directory, never `issues/implemented/`, since a freshly filed bug is by definition not yet
+fixed. `<slug>` is a kebab-case derivation of the title.
+
+## Step 4 — Validate and report
+
+Confirm every field required by `schema.json` is present (including the `kind: "bug"`
+conditional requirements — `symptom` and `rootCause`) and that `chartType`, `status`, and
+`complexity.score` use only their allowed enum values.
+
+Report a short summary: title, chart type, complexity score, whether root cause is
+confirmed or hypothesized, and any `openQuestions` — the user submits this as a PR from
+here.

.claude/commands/generate-chart-spec.md

@@ -0,0 +1,91 @@
+# Generate a Chart Feature Spec
+
+Converts gathered design tokens and requirements into a validated JSON `kind: "feature"`
+spec at `planning/specs/<chartType>/<slug>.json`. The spec is submitted as a PR; once
+approved, the `implement-new-prop` / `implement-new-chart-mark` / `implement-new-child-component`
+skills read it as the authoritative source of requirements, edge cases, and implementation
+plan.
+
+This skill is for not-yet-built features only. For a bug in existing behavior, use the
+`file-issue` skill instead — it produces a `kind: "bug"` spec at
+`planning/specs/<chartType>/issues/<slug>.json`.
+
+Read `planning/specs/README.md` first — it documents the complexity rubric, the edge-case
+checklist, and the `crossCutting` flags referenced below. Read `planning/specs/schema.json`
+for the exact field contract.
+
+`$ARGUMENTS` is whatever the gathering phase produced — freeform text, a path to a notes
+file, a Jira ticket reference, a Figma link, or a combination. Don't assume a fixed upstream
+shape; the gathering process this feeds from is not stable tooling yet.
+
+---
+
+## Step 1 — Read the gathered material
+
+Parse `$ARGUMENTS` for:
+- The target chart type (`bar`, `line`, `donut`, `area`, `scatter`, `combo`, `bigNumber`,
+  `bullet`, `venn`, or `chart` for a chart-level feature)
+- Whatever requirements/design tokens were gathered — read any referenced notes file,
+  fetch the Jira ticket via `mcp__corp-jira__*` if a ticket ref is given, or fetch the
+  Figma node via `mcp__figma__*` if a Figma URL is given
+
+If the chart type is ambiguous or missing, ask before proceeding — it determines both the
+output directory and which existing code to read next.
+
+---
+
+## Step 2 — Explore the relevant code
+
+Read the target mark's `*Options`/`*SpecOptions` types
+(`vega-spec-builder/src/types/marks/<mark>Spec.types.ts`) and its spec builder file(s)
+(`vega-spec-builder/src/<mark>/<mark>SpecBuilder.ts` and related `*Utils.ts` files) — the
+same files `implement-new-prop.md` and `implement-new-chart-mark.md` point to. This grounds
+the implementation plan in real file paths and informs the complexity score.
+
+If the feature plausibly touches hover animation, controlled highlight, legend interaction,
+or tooltip/popover wiring, read the corresponding mechanism directly rather than guessing:
+`hoverAnimationUtils.ts`, the `CONTROLLED_HIGHLIGHTED_TABLE`/`SERIES` usages in the mark's
+mark-utils file, `legendHighlightSignals`, and `isInteractive`/`interactiveMarkName`
+respectively (see `crossCutting` table in `README.md`).
+
+Check whether the mark exists in `vega-spec-builder-s2` — if the s1 file you're reading has
+a sibling there, `requiresS1S2Parity` is likely `true`.
+
+---
+
+## Step 3 — Write the spec
+
+Fill out every required field from `schema.json`:
+
+- `id`, `title`, `chartType`, `kind: "feature"`, `summary`
+- `variant`: `"s1"`, `"s2"`, or `"both"` — whichever package variant(s) Step 2's exploration
+  and the resulting `implementationPlan` actually target. See README.md's `variant` section
+  for how this differs from `crossCutting.requiresS1S2Parity`.
+- `status`: `"approved"` (default — see README.md for why there's no draft/in-review state)
+- `lastUpdated`: run `date +%Y-%m-%d` in a shell and use its literal output — never your own
+  sense of the current date. See README.md's "Stamping lastUpdated."
+- `complexity`: score (`1|2|3|5`) + a one-line rationale, using the rubric in README.md
+- `requirements`: the behavior requirements from Step 1, as discrete bullets
+- `designTokens` / `references`: from Step 1, if any were gathered
+- `edgeCases`: walk the checklist in README.md against this specific feature — don't include
+  entries that don't apply, but do check each one
+- `crossCutting`: answer all six flags explicitly based on Step 2's exploration — never
+  leave a flag `false` without having actually checked it against the code. Add `notes` for
+  any flag that's `true`.
+- `implementationPlan`: one entry per file from Step 2, each with a `change` description and
+  an approximate `lines` range where you have one
+- `openQuestions`: anything you couldn't resolve from the gathered material
+
+Write the file to `planning/specs/<chartType>/<slug>.json` — the base directory, never
+`implemented/`, since a freshly generated spec is by definition not yet built. `<slug>` is a
+kebab-case derivation of the title.
+
+---
+
+## Step 4 — Validate and report
+
+Confirm every field required by `schema.json` is present and that `chartType`, `status`,
+and `complexity.score` use only their allowed enum values.
+
+Report a short summary: title, chart type, complexity score, number of implementation-plan
+entries, and any `openQuestions` — the user submits this as a PR from here.

.claude/commands/implement-bug-fix.md

@@ -4,6 +4,34 @@ Use this skill when fixing a bug. Read `.claude/architecture.md` first — diagn
 
 ---
 
+## Step 0: Check for a Filed Bug Spec
+
+Look for `planning/specs/<chartType>/issues/<slug>.json` matching this bug, checking both
+the base `issues/` directory (still open) and its `implemented/` subfolder (already fixed —
+still useful context, e.g. to check whether this is a regression of a previously-fixed bug).
+If one exists and `status` is `"approved"` or `"implemented"`, read it and start from its
+`symptom`, `rootCause`, `crossCutting`, and `implementationPlan` instead of rediscovering
+them from scratch — `crossCutting` tells you up front whether the fix needs to interact with
+hover animation, controlled highlight, legend interaction, or tooltip/popover wiring, and
+whether S1/S2 parity applies. Use `implementationPlan` as a starting file checklist,
+re-locating by symbol name if its line numbers have drifted.
+
+Treat `rootCause` as a starting hypothesis, not gospel — re-verify it against the current
+code before implementing, since the spec may have been filed before other changes landed. If
+the code no longer matches the spec's description, update the spec (`status:
+"needs-revision"` or a corrected `rootCause`) as part of the fix PR. If no spec exists,
+proceed as below.
+
+Before setting `status` to `"implemented"`, reconcile the whole spec against the final diff —
+see README.md's "Reconcile the whole spec before marking implemented." A discovery made
+mid-implementation (a second file that needed fixing, a `crossCutting` flag that turns out to
+be true) must be reflected everywhere it's relevant, not just in `rootCause`. Any time you
+touch a field, re-stamp `lastUpdated` with the output of `date +%Y-%m-%d` — never a
+hand-written guess. Then `git mv` the file into
+`planning/specs/<chartType>/issues/implemented/<slug>.json` as part of the same PR.
+
+---
+
 ## Diagnosing a Bug
 
 ### Step 1: Identify which layer the bug lives in
@@ -57,6 +85,9 @@ Any mark that is purely visual (annotation text, halo, badge, reference label) m
 ### S2 parity is always required
 When fixing a bug in an s1 file, find the corresponding s2 file (`packages/vega-spec-builder-s2/` mirrors `packages/vega-spec-builder/`). Apply the same fix unless the bug doesn't exist in s2 — but verify, don't assume. S2 has intentional simplifications (no Venn, simpler static point rendering) so don't port s1-specific behavior blindly.
 
+### Comments stay short — no narration of the fix
+New or touched functions get at most a one-line JSDoc (description + `@param`/`@returns`), matching the length of sibling functions in the same file. Do not add paragraphs explaining what bug was fixed, why, or what the investigation found — that belongs in the PR description and commit message, never in the code. See `CLAUDE.md`'s Code Style section for a worked example.
+
 ---
 
 ## Writing the Regression Test

.claude/commands/implement-new-chart-mark.md

@@ -6,6 +6,28 @@ Read `.claude/architecture.md` first — this is the most involved type of chang
 
 ---
 
+## Step 0: Check for an Approved Spec
+
+Look for `planning/specs/<chartType>/<slug>.json` matching this feature, checking both the
+base directory (not yet implemented) and its `implemented/` subfolder (already shipped —
+still useful context, e.g. for a regression). If one exists and `status` is `"approved"` or
+`"implemented"`, read it and treat its `requirements`, `edgeCases`, and `crossCutting` flags
+as authoritative instead of re-deriving them — `crossCutting` in particular tells you up
+front whether this mark needs to interact with hover animation, controlled highlight, legend
+interaction, or tooltip/popover wiring, and whether S1/S2 parity is required. Use
+`implementationPlan` as a starting file checklist, re-locating by symbol name if its line
+numbers have drifted. If no spec exists, proceed as below.
+
+Before setting `status` to `"implemented"`, reconcile the whole spec against the final diff —
+see README.md's "Reconcile the whole spec before marking implemented." A discovery made
+mid-implementation must be reflected everywhere it's relevant (`crossCutting`,
+`implementationPlan`), not just wherever you first noted it. Any time you touch a field,
+re-stamp `lastUpdated` with the output of `date +%Y-%m-%d` — never a hand-written guess. Then
+`git mv` the file into `planning/specs/<chartType>/implemented/<slug>.json` as part of the
+same PR.
+
+---
+
 ## Implementation Steps
 
 ### Step 1: Spec Builder Types
@@ -288,3 +310,5 @@ S2 differences: uses `getS2ColorValue` instead of `getColorValue`, no `s2` boole
 **Cognitive complexity** — SonarQube flags functions whose cognitive complexity exceeds the threshold. Spec builder functions with many conditionals are the most common trigger. When a function grows complex, extract inline conditional chains or loops into named helper functions rather than inlining them. The `addData` and `addMarks` functions are the most likely candidates.
 
 **Copyright header missing** — Every new `.ts`/`.tsx` source file requires the Apache 2.0 copyright block at the top. ESLint enforces this as a hard error. See `.claude/architecture.md` for the exact header text. Story files (`.story.tsx`) are exempt.
+
+**Multi-line JSDoc/comments narrating the change** — New functions get at most a one-line JSDoc (description + `@param`/`@returns`), matching the length of sibling functions in the same file. Do not add paragraphs explaining why the mark was added or what was investigated while building it — that belongs in the PR description, never the code. See `CLAUDE.md`'s Code Style section for a worked example.