Implement Interactive Scientific Application From Spec

---
name: implement-interactive-scientific-application-from-spec
description: Implement an interactive scientific Datagrok application from an approved spec.md
when-to-use: When a spec.md exists and user asks to implement, code, or build the scientific application from it. NOT for CRUD apps.
context: fork
effort: high
---

# Implement Datagrok Scientific Application from Specification

This skill takes an approved specification (`spec.md`) and produces a
complete, working Datagrok application.

**Input:** `spec.md` — created by the `create-interactive-scientific-application-spec` skill or written manually.
**Output:** fully implemented application with tests.

**Base path:** `.claude/skills/implement-interactive-scientific-application-from-spec/` (relative to repo root).
All file paths below use `{SKILL}/` as shorthand.

---

## Step 1: Locate and read the specification

Find `spec.md`:
- If the user provides a path — use it.
- If the current directory is inside an application directory — look for
  `spec.md` there.
- Otherwise — ask the user where the spec is.

Read `spec.md` in full. Verify it contains at minimum:
- Section 1.0 (General Information) with app name and package.
- Section 1.1 (Core) with computation formulas and reference examples.
- Section 3 (Controls) with complete control definitions.
- Section 4 (Display Elements).

If the spec is incomplete or missing critical sections — tell the user
and suggest running the `create-interactive-scientific-application-spec` skill first.

---

## Step 2: Read the architecture guide and references

Read the following files. Read only what is relevant to the current
application — check the spec's complexity level to decide.

**Always read:**

| File | Purpose |
|------|---------|
| `{SKILL}/references/guide.md` | Full implementation guide |
| `{SKILL}/references/reference/datagrok-api-reference.md` | Datagrok inputs, viewers, layouts, subscriptions |
| `{SKILL}/references/reference/datagrok-coding-conventions.md` | File structure, naming, formatting, error handling |

**Read the reference example (complete working implementation):**

| File | Purpose |
|------|---------|
| `{SKILL}/references/examples/lotka-volterra-spec/lotka-volterra-spec.md` | Example spec |
| `{SKILL}/references/examples/lotka-volterra-spec/code/` | Complete implementation following this architecture |

**Read if the spec uses workers (Sections 1.2–1.3 are not N/A):**

| File | Purpose |
|------|---------|
| `{SKILL}/references/reference/WORKER-GUIDE.md` | Worker-utils infrastructure and lifecycle |

**Read if the spec uses parallel execution (e.g., grid search, sensitivity):**

| File | Purpose |
|------|---------|
| `{SKILL}/references/reference/PARALLEL-EXECUTION.md` | Distribution across worker pools |

**Read if the spec involves array-heavy computations:**

| File | Purpose |
|------|---------|
| `{SKILL}/references/reference/COMPUTATION-PATTERNS.md` | Raw data and null handling |
| `{SKILL}/references/reference/ARRAY-OPERATIONS.md` | Efficient typed array operations |

---

## Step 3: Implement in order

Follow this implementation sequence strictly:

1. **Project structure** — create files and directories per the guide.
2. **Model types** — interfaces for input/output ports (Section 1.2 of spec).
3. **Core computation** — implement each task in isolation, no UI imports
   (Section 1.1 of spec). The core must NOT import `datagrok-api` or `ui`.
4. **Validation** — implement `validate()` returning `Map<InputId, string>`
   (Section 7 of spec).
5. **Workers** (if applicable) — worker files in `src/<app-name>/workers/`
   (Section 1.3 of spec). Each worker must be added as a separate entry
   point in `webpack.config.js`:
   ```
   '<worker-name>': {filename: '<worker-name>.js', import: './src/<app-name>/workers/<worker-name>.ts'}
   ```
   Workers are loaded at runtime via
   `new Worker(_package.webRoot + 'dist/<worker-name>.js')`.
6. **UI controls** — create inputs with all options from the spec
   (Section 3 of spec).
7. **Display elements** — viewers, custom panels (Section 4 of spec).
8. **CSS** — all styles in `css/<app-name>.css` with app-specific prefix.
   No inline styles (Section 5.3 of spec).
9. **Coordinator** — connect everything: reactivity, validation triggering,
   computation, result display, resource lifecycle (Section 1.4 of spec).
10. **Tests** — implement test categories from Section 15 of spec.

---

## Step 4: Implementation rules

Follow the architecture guide strictly. Key principles:

- **Hexagonal architecture:** Core ↔ Ports ↔ Adapters ↔ Coordinator.
- **Independence principle:** UI behavior does not depend on computation.
  The core receives a ready, validated parameter set.
- **CSS isolation:** all classes use `<app-name>-` prefix. No generic names.
- **Computation blocking:** use `computationsBlocked` flag for batch updates.
- **Resource cleanup:** collect all subscriptions in `subs[]`, terminate
  workers on close, cancel pending operations.
- **Tooltips:** every control and action button must have a tooltip.
- **Validators:** add Datagrok validators to every input via `addValidators()`.
- **No artificial delays:** if examples contain a `busy wait` loop for demo
  purposes — never reproduce this pattern.
- **Domain names in core:** the core should use domain names (`alpha`, `beta`),
  not UI-prefixed identifiers (`ctrl_alpha`). The coordinator maps between
  domain names and control IDs. Similarly, `RANGES` (slider min/max) belongs
  to the UI adapter, not the core — the core should only define mathematical
  domains (e.g., `> 0`).

---

## When the spec is insufficient

If during implementation you discover that the specification is incomplete,
ambiguous, or inconsistent:

- **STOP coding.**
- Tell the user exactly what is missing or unclear.
- Propose a fix.
- Wait for approval before continuing.

Do NOT improvise or fill gaps silently.

---

## Quality checklist (before presenting the final result)

- [ ] Every computation matches the formulas in the spec exactly.
- [ ] All controls have correct defaults, ranges, formats, and tooltips.
- [ ] Validation covers all rules from the spec with correct error messages.
- [ ] CSS file exists with app-prefixed classes; no inline styles.
- [ ] All event subscriptions collected in `subs[]` array.
- [ ] All workers terminated on close.
- [ ] `onViewRemoved` handler cleans up all resources.
- [ ] Tests cover: validation (boundary + invalid), formula verification,
      output properties, numerical method (if applicable).

---

## Reference files summary

| File | Required | When |
|------|----------|------|
| `references/guide.md` | Yes | Always |
| `references/reference/datagrok-api-reference.md` | Yes | Always |
| `references/reference/datagrok-coding-conventions.md` | Yes | Always |
| `references/reference/WORKER-GUIDE.md` | Conditional | Spec uses workers |
| `references/reference/PARALLEL-EXECUTION.md` | Conditional | Spec uses parallel execution |
| `references/reference/COMPUTATION-PATTERNS.md` | Conditional | Array-heavy computations |
| `references/reference/ARRAY-OPERATIONS.md` | Conditional | Typed array operations |
| `references/examples/lotka-volterra-spec/` | Yes | Complete reference implementation with spec |