Canonical example of a domain.implementation_notes Capsule. Documents the decisions, deviations, tradeoffs, and open questions from implementing a hypothetical CSV-to-interactive-dashboard generator against a written spec.
specs/csv-dashboard-spec.mdWhat got built: A CLI tool that accepts a CSV file, infers column types, and produces a single self-contained HTML dashboard with bar charts, line charts, and a sortable data table. Output conforms to the Capsule Core spec.
Choices made where the spec was ambiguous or silent.
Decision
Use SVG for charts instead of canvas
Context: The spec said "render charts" but didn't specify the rendering technology.
Rationale: Accessibility and printability both matter for capsule-format output. Canvas pixels don't survive PDF export cleanly. SVG is also copy-pasteable into other tools.
Alternatives considered:
Decision
Type inference uses a fixed pipeline: number, boolean, date, string
Context: Spec did not define type inference rules.
Rationale: Predictable, debuggable, no statistical sampling needed for small CSVs. Larger CSVs may need a different approach later, but the fixed pipeline ships faster.
Alternatives considered:
Decision
All data lives inline in the data block as parsed JSON, not as raw CSV
Context: Spec said "package the source data with the dashboard" without specifying format.
Rationale: Already parsed once during type inference. Re-parsing CSV at runtime adds error surface. JSON is queryable from the runtime without a CSV parser.
Alternatives considered:
Places the implementation intentionally departs from the spec.
Section 3.2: Date handling
Failed-parse dates are stored as strings, not nulled
Why: Nulling silently loses information that a human reviewer needs to see. The string preserves what was in the source so the reviewer can decide whether to fix the data or relax the parser.
Reversible: yes. Could be brought back into spec compliance later.
Section 4.1: Chart auto-selection
All three chart types shown regardless of column type
Why: The spec said "auto-select the best chart type for each column." Auto-selection is opinionated and frequently wrong. Showing all three lets the user pick. Auto-selection is the obvious follow-up but should not block v0.1.
Reversible: yes.
Alternatives considered, and why this one.
Tradeoff
Reactive vs. static dashboard behavior
Question: Should the dashboard be reactive (a filter syncs across all charts) or static (each chart independent)?
Options considered:
Chosen: Static for v0.1
Why: Reactive needs more runtime complexity and increases the chance of bugs that mutate the data block (Core rule 6 forbids modifying capsule-data at runtime). Static ships sooner. Reactive is the obvious v0.2 move.
Tradeoff
Aggregations: precompute or on-demand?
Question: Should aggregations (sum, mean, count) be precomputed at build time or computed in the runtime?
Options considered:
Chosen: Precompute the common ones (count, sum, mean, min, max), compute others on demand
Why: Precomputed values survive in plain-HTML view (no JS needed), satisfying Core rule 12. On-demand computation handles arbitrary queries without bloating the file.
Things the implementer wants the spec author to confirm or revise.
Open question medium
What is the size cap for embedded CSV data?
The capsule hard cap is 15 MB. Section 6 did not specify whether the implementation should warn earlier. Currently warns at 5 MB, hard-stops at 15 MB.
Open question low
Source CSV preservation: bit-exact or semantic?
Section 7.3 said "preserve source." Unclear whether that means bit-exact preservation of the original CSV bytes or semantic preservation via the parsed JSON.
Open question high
How should the dashboard handle CSVs with no header row?
Not addressed in the spec. Currently the implementation assumes a header row exists. CSVs without one fail loudly. High urgency because this is a common real-world input.
How AI consumers should and shouldn't reason from this capsule.
Technical, plainspoken, calibrated about uncertainty.
Take this capsule's content somewhere else.
This is a canonical example of a domain.implementation_notes Capsule per spec/DOMAIN_CAPSULES.md. It is hand-written rather than LLM- or compiler-produced, which is reflected in generator.kind = "human".
Loading manifest...