How I built FrankenData with Kiro: spec-first, one small batch at a time

Every data person has two spreadsheets that describe the same things with different column names. One says Threat_Level, the other says danger_level. One has duplicate rows, the other spells "swamp wraith" three different ways. Fixing that by hand is grave-robbing work: dig out the good parts, sew them together, hope it holds.

For Kiroween 2026 I built the lab for it. FrankenData takes mismatched CSV and XLSX files, proposes how to stitch them together, cleans them, joins them into one typed DuckDB table, and then lets you ask it questions in plain English. All of it runs in your browser. Your rows never leave the tab.

Try it: kiroween-frankendata.vercel.app · Code: GitHub

This post is about how I built it with Kiro, and what I would do the same way again.

Specs first, code second

I did not start by asking Kiro to "build a CSV app". I started with three specs, each with requirements.md, design.md and tasks.md:

Writing the requirements forced decisions I would otherwise have made by accident. For example: the AI may only re-score matches the rules engine already found, never invent one, and an AI-discovered match can never reach the auto-approve threshold. That rule lives in the spec, so every later task had to respect it.

Then I executed tasks in small batches, a few at a time, and stopped after each batch to run the build, the tests, lint and a serverless check. Big "do everything" prompts went wrong more often and cost more to fix. Small batches with a hard checkpoint almost never did.

Steering docs that load when they matter

Steering docs were how I stopped repeating myself. FrankenData has six, and the part I liked most was the inclusion modes:

• Always on: product.md, tech.md, structure.md and security.md. The security doc holds the rules that must never drift: data stays in the browser, only column names and a few sample values ever leave, the proxies fail closed, and no secret ever reaches the client bundle.
• Only when editing API files: api-conventions.md. Node (req, res) handlers, explicit .js import extensions, shared helpers, and the rule that npm run check:api must pass.
• Only when editing test files: testing.md. Vitest settings, property tests for invariants, golden DuckDB tests.

Loading API and testing rules only when they apply keeps the agent's context focused on the task in front of it, instead of every rule I ever wrote.

Hooks as guardrails

FrankenData turns plain English into SQL and runs it. The thing standing between a model and a destructive query is the SQL validator: one read-only SELECT or WITH, only over loaded tables, no file or network functions, no extra statements, a row cap.

That file is the one I least wanted an agent to "helpfully" loosen while fixing something else. So I added a hook, sql-validator-guard, that fires whenever sql-validator.ts is edited and asks the agent to re-run the validator's unit and property tests and confirm no forbidden-keyword or file and network check was weakened.

The other three hooks are simpler: run-test-suite, check-api for the serverless function graph, and pre-commit-quality-gate, which runs build, lint and tests before a commit. Small, boring, and they caught real problems.

Properties in the spec became property tests

The design docs list correctness properties, not just features. Kiro turned them into fast-check property tests that throw hundreds of random inputs at each rule. A few of them:

• Undo restores state: after apply then undo, the exact pre-apply tables and contents are back.
• Apply never mutates originals: every original table is byte-for-byte unchanged after a stitch.
• LEFT JOIN row floor: the stitched result never has fewer rows than its anchor table.
• Injection safety: adversarial table names and values never execute injected SQL.
• Bounded AI influence: whatever the model says, a score moves only within fixed bounds.
• Validator rejects forbidden statements: random SQL containing forbidden keywords is always refused.

By the end the suite had 101 test files and 688 tests. That made it safe to keep changing the UI late in the project, because anything that touched the core broke a property loudly.

What broke in production

Passing tests did not mean a working deploy. Three bugs only showed up on the live site:

1. ERR_MODULE_NOT_FOUND on the AI proxy. Node's ESM resolution needs explicit .js extensions in imports, and Vite never complained. Kiro fixed the imports and added a check:api script that type-checks, emits, imports and actually invokes the handlers. That rule now lives in api-conventions.md.
2. req.text is not a function. The handlers were written for web Request objects, but the runtime passes Node-style (req, res). Kiro rewrote them with a capped body reader, and check:api now calls each handler to prove it.
3. Dates showing as 1764460800000. DuckDB returned dates as epoch milliseconds. The fix reads the column types and formats dates properly.

Each fix was a short, focused Kiro prompt with the exact error and log line pasted in. Specific errors got specific fixes.

What I would do again

• Write the safety rules into the spec, not into prompts. The AI's limits held for the whole project because they were requirements, not reminders.
• Run tasks in small batches with a hard checkpoint. Build, tests, lint and the serverless check after every batch.
• Scope steering docs with inclusion modes, so each rule shows up only where it applies.
• Put a hook on your most dangerous file. Mine was the SQL validator.
• Budget your credits. I ran out of monthly credits near the end, so I parked the last UI batch on a branch and merged it once it built cleanly.

And the fun part: the app has a little mascot, the Specimen, a creature stitched together from spreadsheet cells. It sleeps on its slab until you load data, comes alive with a lightning strike, gets bandaged when you stitch, and holds up a chart when you get an answer. Poke it.

Try FrankenData: kiroween-frankendata.vercel.app · Code: github.com/Kadaru242003/kiroween-frankendata

Built for the Kiroween 2026 hackathon.