← All craftbooks

CSV / Tabular Transformer

Data and analysisevalv1.2.1released 2026-07-16workflow: build-loop

Steps

Entry step: schema-scope. Each step names the specialist role it wants; the full working prompt is expandable.

1. Scope the schema mappingplannerentry

   lock the input schema, target schema, and field-by-field mapping

   Show working prompt

   Define the transform contract before writing any code. Step 1: document the INPUT schema (columns, types, format/delimiter) from a sample of the source. Step 2: document the TARGET schema (columns, types, order, output format). Step 3: write the field-by-field mapping table: each target column = which source column(s) and the transform (rename, cast, split on delimiter, concatenate, derive via formula, constant). Step 4: define row-level rules — filters to apply, dedup, how to handle missing source values, and pivot/unpivot if the shape changes. Step 5: write an acceptance-criteria checklist ('output has exactly the target columns in order', 'output parses in the target format', 'row count matches the filter rule', 'a sampled row maps correctly end-to-end', 'no data type errors'). Call write_task_note and write the mapping table + rules + checklist to notes/schema-scope.md.

2. Build the transformdeveloper

   apply the mapping and emit the target file

   Show working prompt

   Implement the transform exactly to the mapping table. Step 1: read the input with the correct delimiter/encoding. Step 2: apply each target column's rule in order (rename, cast, split/join, derive, constant); reshape (pivot/unpivot) if specified. Step 3: apply row filters and dedup; track rows-in vs rows-out and the reason for any drop. Step 4: write the output to data/output.csv (or the requested format/extension) with the target columns in the exact specified order and a header row. Step 5: ensure the output parses (valid CSV/JSON) and types are clean (no '1.0' where an int is expected). On a loop-back, fix only the named gaps. Call write_task_note with the path and rows-in/rows-out.
   
   Produce the output by EXECUTING your transform (prefer `derive_file({ script, outputPath })`, or write a script file and run it with `run_nodejs_script`); do not hand-type rows into the output file — hand-typed derived data loses records.

3. Evaluatereviewer

   Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

   Show working prompt

   Open data/output.csv and verify it matches the schema-scope contract. Step 1: confirm it parses in the target format and has EXACTLY the target columns in the specified order. Step 2: re-count the rows and reconcile against input — the count must equal input rows after the documented filter/dedup, with the delta explained. Step 3: pick 3 source rows and trace them through the mapping by hand to confirm each target field is correct end-to-end. Step 4: scan for type errors (e.g. '1.0' where an int is expected) and stray nulls the mapping didn't intend. Write PASS/FAIL per criterion; any FAIL loops back to build.
   
   Then route — this is the whole point of the loop:
   
   - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
   - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps.
   
   Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.

4. Finishdeveloper

   All acceptance criteria met. Stamp a short summary and report DONE.

   Show working prompt

   Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

• reshape a csv
• convert csv to json
• remap columns
• transform tabular data
• reformat a data export

Source

View this craftbook on GitHub · MIT license