Planning Questions

Questions

PQ1 — Agent Execution Strategy

Description: The project has a linear phase dependency chain (0 → 1 → 2 → 3 → 4 → 5). The only parallelism opportunity is within Phase 2 (7 independent cell types) and within Phase 4 (ActionCellRenderer can be built in parallel with Wave 3a tasks). Total scope: ~30 new/ported component files + ~30 test/story files.

Options:

• (a) Single agent, sequential execution — One agent works through all phases in order. Phase 2 cell types are done one after another.
  • Pro: Zero coordination overhead. No worktree setup. Simple to debug.
  • Con: Slower for Phase 2 (7 independent cell types serialized).
• (b) Team with 2-3 agents for Phase 2 only — Single agent for Phases 0-1 and 3-5. Team of 2-3 agents for Phase 2 cell types.
  • Pro: Phase 2 parallelized (~14 components across 2-3 agents).
  • Con: Worktree setup overhead. Merge coordination for 7 directories created in parallel. Cell types are small (~50-100 lines each) — parallelism overhead may exceed time saved.
• (c) Full team execution — Team lead + specialized agents per phase.
  • Pro: Maximum parallelism for independent tasks.
  • Con: The linear dependency chain means most phases serialize anyway. Only Phase 2 benefits.

Recommendation: (a) Single agent, sequential execution. The linear dependency chain eliminates most parallelism benefit. Phase 2 cell types are small enough (copy + update imports + adapt tests/stories ≈ 15-30 min per type) that serialization is acceptable. The new cell types (memo, color) require creative work that benefits from a single agent’s context continuity. Coordination overhead of a team would likely exceed the time saved.

Rationale: Per the agent team task splitting heuristic: “number of unique source files × mock complexity” is a better proxy than statement count. Here, each cell type is a unique source file with minimal mock complexity (no API mocks, no context providers). Template-replicable work (5 ported cell types following the same copy+adapt pattern) finishes quickly in serial.

PQ2 — Memo Hover Overlay Implementation

Description: The MemoCellDisplay (Phase 2, T2.6) needs to show full text in a hover overlay after a configurable delay per Q12 decision. The project has no src/components/ui/ directory (no shadcn component wrappers). Radix packages are present as transitive dependencies from other components.

Installed Radix packages (verified in node_modules/@radix-ui/):

• react-tooltip — present (simple tooltip, limited layout control)
• react-popover — present (rich content, click-triggered by default)
• react-dialog, react-dropdown-menu — present (not relevant for hover)
• react-hover-card — NOT installed

Options:

• (a) Use @radix-ui/react-tooltip — Already installed. Wraps content in a tooltip on hover with configurable delay (delayDuration prop).
  • Pro: No new dependency. Simple API. Built-in hover delay. Accessible (aria-describedby).
  • Con: Tooltip is designed for short text hints, not multi-line content. Limited layout control — content is positioned by Radix and may clip at viewport edges. Styling is constrained.
• (b) Install @radix-ui/react-hover-card — New direct dependency (npm install @radix-ui/react-hover-card). Designed for rich hover content with open/close delay control.
  • Pro: Purpose-built for this use case (preview cards on hover). Supports openDelay/closeDelay. Rich content layout (images, multi-line text, custom components). Better than tooltip for long text.
  • Con: Adds a new direct dependency (~15KB). Not currently used anywhere in the project.
• (c) Use @radix-ui/react-popover — Already installed. Rich content overlay. Normally click-triggered but can be controlled programmatically for hover behavior via open/onOpenChange + mouse event handlers.
  • Pro: No new dependency. Full layout control. Already used elsewhere in the project.
  • Con: Not designed for hover — requires manual onMouseEnter/onMouseLeave wiring with timeout management. More code to replicate what HoverCard does natively.
• (d) Use AG Grid’s native tooltipComponent — Configure tooltipValueGetter and tooltipComponent on the column definition.
  • Pro: No new dependency. AG Grid manages the tooltip lifecycle.
  • Con: Rejected per Q12 decision (AG Grid tooltip styling is limited).

Recommendation: (a) Use @radix-ui/react-tooltip. It’s already installed, has built-in hover delay (delayDuration), and is sufficient for showing expanded text content. While it’s simpler than HoverCard, the use case (show truncated cell’s full text on hover) is exactly what tooltips are for. If the layout proves too constrained during implementation, upgrading to react-hover-card is a small change (similar API, same Radix conventions).

PQ3 — Color Palette Default Source

Description: The ColorCellEditor (Phase 2, T2.7) needs a configurable color palette with a default. Q13 decision says: “Configurable. Default should be a continuous palette. OK to source from shadcn or Radix if available.”

Vendored reference implementation: The vendored ColorCellEditor (class-based, raw DOM, ~125 lines in ItemTableAGGrid.tsx) uses a native <select> with 10 color options. The vendored color renderer (~30 lines in columnPresets.tsx) shows a 4x4px rounded swatch + label. Both use a hardcoded color map:

RED: #EF4444, GREEN: #22C55E, BLUE: #3B82F6, YELLOW: #FDE047,
ORANGE: #F97316, PURPLE: #A855F7, PINK: #EC4899, GRAY: #6B7280,
BLACK: #000000, WHITE: #FFFFFF

The constants.ts file has a colorOptions array with 8 entries (missing BLACK and WHITE).

Options:

• (a) Mimic vendored using React/shadcn/Radix — Reimplement the vendored color display (swatch + label) and editor (dropdown with swatches) using React components with shadcn/Radix primitives. Use the vendored 10-color map as the default palette, configurable via colors: ColorOption[] prop.
  • Pro: Consistent with canary React component patterns. Full control over styling. Configurable palette.
  • Con: Slightly more code than a plain <select>.
• (b) Radix Colors — Use @radix-ui/colors for accessible color scales.
  • Pro: Accessible contrast ratios.
  • Con: New dependency. Doesn’t match the vendored color set.
• (c) Hardcode a sensible default — Define a default array using the vendored 10 colors.
  • Pro: Zero dependency. Matches vendored behavior.
  • Con: Not configurable without code changes.

Recommendation: (a) Mimic vendored using React/shadcn/Radix. The canary ColorCellDisplay replicates the vendored swatch + label pattern. The canary ColorCellEditor replaces the raw-DOM class-based editor with a React forwardRef component using a shadcn/Radix Select or Popover for the dropdown. The vendored 10-color map serves as the default palette. The colors: ColorOption[] prop allows consumers to override.

PQ4 — Canary-Refactor Story Import Strategy

Description: Phase 5 forks vendored components (ItemsPage, ItemTableAGGrid, columnPresets) into canary-refactor/components/. These forked files import both canary components (grid infrastructure) and vendored components (page chrome, panels, domain editors) via @frontend/ paths. The @frontend alias is configured only in Storybook’s Vite config (.storybook/main.ts), not in tsconfig.json.

Options:

• (a) Use @frontend/ alias for vendored imports — Forked files import vendored components via @frontend/components/*, same as the dev-witness stories.
  • Pro: Consistent with existing pattern. No alias changes needed.
  • Con: TypeScript will show “Cannot find module” errors for @frontend/ imports in the IDE (Storybook resolves them at runtime but tsconfig.json doesn’t know about the alias). This is an existing issue with dev-witness stories.
• (b) Add @frontend alias to tsconfig.json — Configure the path alias so TypeScript resolves vendored imports in both Storybook and IDE.
  • Pro: No red squiggles in IDE. Better DX.
  • Con: Changes the TypeScript config. May have unintended side effects if vendored types leak into the build.
• (c) Use relative paths — Forked files import vendored components via relative paths like ../../../vendored/arda-frontend/components/*.
  • Pro: No alias dependency. TypeScript resolves natively.
  • Con: Deep relative paths are fragile and hard to read.

Recommendation: (a) Use @frontend/ alias. This matches the existing dev-witness pattern. The TypeScript “Cannot find module” issue is a known trade-off documented in the How to Extract and Publish guide (ux-prototype/src/docs/workflows/canary-components/how-to-extract-and-publish.mdx).

PQ5 — Storybook Dev Server for VRT

Description: VRT tests in Phases 0 and 5 require Storybook to be running. The project has two VRT approaches: test:vrt (expects Storybook running on port 6006) and test:vrt:ci (starts an HTTP server from storybook-static). Building storybook-static takes time.

Options:

• (a) Use npm run storybook (dev server) — Start Storybook dev server manually before running VRT.
  • Pro: Fast iteration. No build step.
  • Con: Requires manual server management. Agent must start/stop Storybook.
• (b) Use npm run build-storybook + test:vrt:ci — Build static Storybook, then run VRT against it.
  • Pro: Deterministic. No dev server management.
  • Con: Storybook build is slow (~2-5 minutes).
• (c) Skip VRT during development, run only in Phase 5 — Rely on unit tests and visual inspection during Phases 1-4. Run VRT only in Phase 5 for final validation.
  • Pro: Fastest development cycle. VRT is a final gate, not a per-phase check.
  • Con: VRT issues discovered late may require backtracking.

Recommendation: (c) Skip VRT during development, run only in Phase 5. VRT baselines are captured in Phase 0 (against identical clones). Phases 1-4 don’t change the canary-refactor stories — they only create new canary components. VRT becomes meaningful only in Phase 5 when the stories are swapped. Running VRT earlier adds build time without catching issues.

Summary

#	Question	Recommendation	Decision
PQ1	Agent execution strategy	Single agent, sequential	Agreed
PQ2	Memo hover overlay	Use @radix-ui/react-tooltip (already installed). Upgrade to react-hover-card if layout is too constrained.	Agreed
PQ3	Color palette default source	Mimic vendored using React/shadcn/Radix. Vendored 10-color map as default, configurable via colors prop.	Agreed
PQ4	Canary-refactor import strategy	Use @frontend/ alias (existing pattern)	Agreed
PQ5	VRT timing	Skip VRT during development, run only in Phase 5	Agreed