# Import Mapping Feedback Loop

> How to add explicit import-time column/material mapping without weakening deterministic defaults

- Skill: `majiayu000/import-mapping-feedback-loop` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/import-mapping-feedback-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/import-mapping-feedback-loop/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/import-mapping-feedback-loop

---


## Context

Use this when a file import flow must keep its exact-match happy path, but still let users recover from mismatched headers or unknown material names inside the app.

## Pattern

1. **Keep the default strict.** Exact header/material matches should continue to work with zero extra input.
2. **Return mapping metadata on every import response.** Include detected source columns, required field mapping status, and unique imported material resolutions so the UI can react without inventing its own parser.
3. **Suggest, don’t auto-apply.** Deterministic header aliases (`Part Id` → `Id`, `Qty` → `Quantity`) are useful as suggestions, but require an explicit user mapping before import succeeds.
4. **Separate pure import from side effects.** Let the service layer consume explicit mappings; let the bridge/app layer create missing library entities first, then rerun import with the created ids.
5. **Rewrite imported material values to the resolved library name before validation.** That keeps downstream project/nesting flows working with canonical material names.
6. **Keep the UI two-speed.** Let exact header/material files stay on the fast import path, but hold mismatched files in a review session that tracks pending mapping edits, requires an explicit preview refresh after operator changes, and only creates new materials on final commit.

## Good signs

- The same `import-file` route can support first-pass analysis and final import.
- Unknown materials are listed once per source value with a stable status (`resolved`, `unresolved`, `created`).
- Row validation codes stay actionable instead of disappearing behind bridge-only errors.

## Anti-patterns

- Auto-mapping fuzzy headers without telling the user.
- Creating materials inside the pure parser/validator service.
- Returning only row errors and forcing the UI to re-open the file itself to learn what headers existed.