importer-scaffolder

name: importer-scaffolderdescription: "Use when asked to build an importer from a competitor's export, migrate users' data from another tool, map a CSV or JSON export onto my data model, or make switching to my project easy. Given a sample export (CSV or JSON), produces a field mapping table, an importer code skeleton, a rule that unmatched records are kept rather than dropped, and test fixtures including the awkward cases. For a database migration inside one system, use database-migration-plan."version: 1.0.0

Importer Scaffolder

People switch tools when leaving costs them nothing, and an importer is how a small project removes that cost. Importers fail quietly: a column is renamed, a date is in another format, a record has no match, and data disappears without anyone noticing. This skill builds an importer from a real sample export, with a mapping that is explicit and a rule that nothing is silently dropped.

Required Inputs

Ask for these if not provided:

• A sample export: a few rows of CSV or a JSON excerpt, with any personal data replaced
• The source tool and how users produce the export
• Your data model: the target fields, types and required fields
• Your language and stack for the importer
• Where unmatched data should go: a notes field, an extras column, or a separate file

Output Structure

1. Source profile

What the sample shows: format, encoding, delimiter, header names, date and number formats, nested fields, and anything ambiguous. List assumptions explicitly.

2. Field mapping table

Every source field appears in the table, mapped or not. Unmapped fields go to the extras destination named in the inputs.

3. The keep-everything rule

State it in the code and the docs: no source record is dropped. A record that fails validation is imported with what could be parsed, flagged, and listed in an import report; its raw source is preserved in the extras destination.

4. Importer skeleton

Code in the requested language with these parts, each a small function:

• read(source): streams rows; detects encoding and delimiter; never loads a huge file whole
• mapRow(row): applies the mapping table; returns { record, warnings, extras }
• validate(record): required fields and types; returns problems without throwing
• write(record): idempotent upsert keyed on a stable source ID, so re-running an import does not duplicate data
• report(): counts of imported, imported with warnings, and per-warning examples

Include a dry-run mode that prints the report without writing.

5. Test fixtures

Fixture files plus the expected result for each:

• the happy path (three normal rows)
• a renamed or reordered header
• an empty required field
• a malformed date and a number with a thousands separator
• non-ASCII text (accents, Chinese characters, emoji)
• a duplicate row (checks idempotency)
• a row with extra unknown columns (checks they land in extras)

6. User-facing instructions

Five to eight steps telling users how to export from the source tool and import, including what the import report means.

Quality Checks

• Every source field in the sample appears in the mapping table
• The code imports invalid records with a flag instead of dropping them
• Unmapped fields are preserved in the named extras destination
• Re-running the import on the same file creates no duplicates
• A dry-run mode exists and writes nothing
• Fixtures cover non-ASCII text, a malformed date and a duplicate row
• The sample data contains no real personal data

Anti-Patterns

• Silent drops. A skipped row is lost data the user may never notice.
• Mapping by column position. Exports reorder columns; map by header name.
• Loading the whole file into memory. Real exports are bigger than samples.
• Guessing ambiguous dates. If 03/04 could be either order, ask or detect from the whole file, and record the choice.

Example Trigger Phrases

• "Build an importer for Trello JSON exports into my app."
• "Here's a CSV export from Notion, map it onto my data model."
• "Make it easy for users to switch from [competitor] to my project."
• "Write a CSV importer that never drops rows."