Scoping & Cutting Pack — Bulk CSV Import for Admins

1. Context snapshot

• Product: Bulk CSV import feature for the admin panel of a B2B SaaS platform
• Target user/segment: Platform admins who need to onboard, update, or migrate records (users, accounts, products, etc.) in bulk rather than one-by-one through the UI
• Decision: Ship a Minimum Lovable Slice of bulk CSV import within a 4-week appetite
• DRI: Product Manager (assumed; to be confirmed)
• Appetite / ship date: 4 weeks (hard time budget). Scope is the variable; the deadline is not.
• Team (assumed): 2 backend engineers, 1 frontend engineer, 1 designer (part-time), QA embedded
• Constraints:
  • Privacy/legal: Uploaded files may contain PII. Files must not be stored longer than necessary; must comply with data-handling policies. No third-party processing of raw files.
  • Reliability: Import failures must never silently corrupt existing data. Partial failures must be recoverable without re-uploading.
  • Platform: Admin panel is a React SPA with a standard REST API backend. No existing file-processing infrastructure.
  • Dependencies: Auth/permissions system already supports admin roles. No new roles needed for V1.
  • Capacity: 4 weeks of a small team; coordination overhead must stay low.

2. Outcome + hypothesis (MVP = test)

Outcome (user value): Admins can import a list of records from a CSV file into the platform in minutes instead of hours of manual data entry, with confidence that errors are caught before data is committed.

Key hypotheses:

1. Value hypothesis: We believe platform admins who currently create records one-by-one will adopt bulk CSV import if the upload-to-confirmation flow takes under 5 minutes for a typical file (< 5,000 rows), because manual entry is their top-reported pain point in support tickets.
2. Usability hypothesis: We believe admins can successfully map CSV columns to platform fields using smart defaults (auto-matching by header name) without needing documentation or support, because header names are predictable for 80%+ of cases.
3. Trust hypothesis: We believe admins will trust the import process if they see a clear preview of changes and an itemized error report before committing, because "fear of breaking data" is the #1 blocker cited in discovery interviews (assumed).

Success metric(s):

• Primary: >= 60% of admins who start an import complete it successfully on their first attempt (task completion rate)
• Secondary: Average time-to-import for a 1,000-row file < 5 minutes (end-to-end)
• Adoption: >= 30% of admins who currently create records manually use CSV import within 4 weeks of launch

Guardrails (must not worsen):

• Data integrity: Zero silent data corruption. Every row either succeeds or is reported as failed with a reason.
• Support load: Import-related support tickets stay below 5% of total admin tickets in the first month.
• System performance: Import processing must not degrade API response times for other admin operations by more than 10%.
• Security: No PII exposure via logs, temp files, or error messages. Files purged within 24 hours.

3. Appetite + success bar

• Time budget (appetite): 4 weeks. Fixed. Non-negotiable.
• Team: 2 BE, 1 FE, 0.5 Design, QA embedded. No additional hires or contractors.
• "Done means...":
  • An admin can upload a single CSV file, see a column-mapping screen with auto-suggested mappings, preview the first 10 rows of mapped data, review a validation report (errors/warnings), confirm the import, and see a summary of imported/failed rows.
  • The feature is behind an admin-only permission and accessible from the admin panel sidebar.
  • Basic documentation (in-app help text + a short knowledge base article) exists.
• Non-negotiables:
  • Validation must run before data is committed (no "import then fix" pattern)
  • Errors must be row-level and downloadable (admin gets a CSV of failed rows with reasons)
  • Files containing PII must be purged from server storage within 24 hours
  • The import must be idempotent-safe for the happy path (re-uploading the same file doesn't create duplicates if a unique key is present)

4. Minimum Lovable Slice (MLS) spec

Core end-to-end flow (happy path):

1. Upload: Admin navigates to "Import" in the admin sidebar and uploads a single .csv file (drag-and-drop or file picker). Max file size: 10 MB.
2. Column mapping: System auto-matches CSV headers to platform fields by name similarity. Admin reviews and corrects mappings via dropdowns. Unmapped columns are shown but skipped.
3. Preview + validate: System parses the first 10 rows with mapped columns and shows a preview table. Full validation runs in the background. Admin sees a summary: X rows valid, Y rows with errors, Z warnings.
4. Error review: Admin can view error details (row number, field, reason) and download a "failed rows" CSV. Warnings (e.g., truncated values) are shown but don't block import.
5. Confirm + import: Admin clicks "Import N rows." System processes the file. A progress indicator shows completion. On finish, admin sees a summary: N imported, M failed, with a link to download the error file.
6. Done state: Success confirmation with a count and a link to view the imported records in the admin list view.

Must-haves (ship in this appetite):

• Single CSV file upload (one entity type per import; e.g., "Users" or "Products")
• Auto-suggested column mapping with manual override
• Pre-commit validation with row-level error reporting
• Downloadable error CSV (failed rows + reasons)
• Progress indicator during import
• Idempotent handling when a unique key column is mapped (update-or-create)
• Admin-only access (existing permission system)
• UTF-8 file encoding support
• In-app help text on the upload screen (accepted format, column requirements, file size limit)

Lovability elements (trust + clarity):

1. Smart defaults for column mapping: Auto-match by header name so admins aren't starting from scratch. This is the single biggest UX win -- it turns a tedious step into a confirmation step.
2. "Dry run" preview with validation before commit: Admins see exactly what will happen before anything changes. This directly addresses the "fear of breaking data" blocker.

Explicit non-goals (won't do now):

• Importing multiple files in one session or batch queuing
• Importing multiple entity types in a single CSV
• Custom field mapping templates (save/reuse mappings)
• Scheduled/recurring imports
• XLSX, JSON, or other file format support
• Complex encoding support (Shift-JIS, ISO-8859, etc.)
• Real-time collaboration (multiple admins importing simultaneously to the same entity)
• Undo/rollback of a completed import
• API-based import (programmatic / headless)
• Advanced data transformation (split columns, merge columns, regex transforms)
• Import history / audit log beyond the current session

Assumptions:

• A1: Most admin CSV files are < 5,000 rows and < 10 MB (covers 90%+ of use cases based on assumed data)
• A2: CSV headers are predictable enough that simple string-similarity matching will auto-map correctly for 80%+ of columns
• A3: Admins will accept a page-refresh-style progress indicator (no real-time WebSocket updates needed)
• A4: One entity type per import is sufficient for V1 (admins don't need to import Users + their Accounts in a single file)
• A5: The existing REST API can handle row-by-row inserts at acceptable speed for < 5,000 rows (no need for bulk DB operations in V1)

5. Cut list (keep / cut / defer)

Decision rationale summary: Cuts prioritize removing breadth (formats, automation, advanced features) while preserving depth on the happy path (upload, map, validate, confirm). Every cut item that could impact trust or data integrity has a mitigation noted. Deferred items have concrete revisit triggers tied to adoption metrics or customer feedback thresholds.

6. Validation plan (Wizard-of-Oz / concierge)

Top assumptions to validate (ranked by risk):

1. A2 (Column auto-mapping accuracy): Smart defaults will correctly auto-map >= 80% of columns for typical admin CSVs. If wrong, the mapping step becomes tedious and the usability hypothesis fails.
2. A1 (File size / row count distribution): Most admin files are < 5,000 rows / < 10 MB. If wrong, the V1 architecture (synchronous processing, no streaming) will hit performance walls.
3. A4 (Single-entity-per-import sufficiency): Admins don't need multi-entity import in V1. If wrong, the core flow feels incomplete.

Validation Test 1: Column Mapping Wizard-of-Oz (Week 1)

Method: Wizard-of-Oz with manual mapping review

Audience: 5-8 existing admins who have reported manual data entry pain (recruit from support ticket history or customer success contacts)

Script / flow:

1. Send a brief email inviting admins to try a "new bulk import prototype" and ask them to reply with a sample CSV they'd typically want to import (anonymized/test data is fine; offer a test-data template if they can't share real data).
2. Collect 5-8 real CSV files from admins.
3. Manually run a simple Python script (string-similarity matching against our platform's field names) on each file to generate auto-mapping suggestions.
4. Present each admin with a mockup/spreadsheet showing: "Here's what we'd auto-map. Which ones are correct? Which would you change?" (Can be done via a shared Google Sheet or a clickable Figma prototype.)
5. Record: (a) % of columns correctly auto-mapped per file, (b) time admin spends reviewing/correcting, (c) qualitative feedback on trust and clarity.

Data to collect:

• Auto-map accuracy rate per file (% of columns correctly matched)
• Average correction count per file
• Qualitative: "Did the suggestions feel right? Would you trust this?"
• Header naming patterns (to improve the matching algorithm)

Success criteria:

• = 80% of columns are correctly auto-mapped across the sample files (aggregate)

• Average review/correction time < 2 minutes per file
• No admin expresses distrust of the mapping suggestions

Failure criteria:

• Auto-map accuracy < 60% across sample files (mapping step becomes tedious, not a confirmation)
• Multiple admins express confusion or distrust of suggestions
• Header naming is too diverse for simple string matching to work

Timeline: Days 1-5 (Week 1). Recruit on Day 1-2, collect files Day 2-4, run analysis + mockup review Day 4-5.

Pivot plan if it fails: Invest in a more guided manual mapping UX (drag-and-drop, grouping by data type) rather than relying on auto-suggestions. Alternatively, provide 2-3 pre-built mapping templates for the most common entity types.

Validation Test 2: File Characteristics Survey (Week 1, parallel)

Method: Concierge data collection

Audience: Same 5-8 admins + a broader survey to 20-30 admins via in-app prompt or email

Script / flow:

1. Ask admins: "When you need to import data, roughly how many rows are in a typical file? What format (CSV, XLSX, other)? How often do you import?"
2. If sample files were collected in Test 1, directly measure row counts, file sizes, and encoding.

Data to collect:

• Distribution of file sizes (rows, MB)
• Distribution of file formats
• Import frequency per admin

Success criteria:

• = 80% of reported files are < 5,000 rows and < 10 MB

• = 80% of files are CSV or easily convertible to CSV

Failure criteria:

• 30% of files exceed 10 MB or 50K rows (V1 architecture is insufficient)

• 30% of files are XLSX-only with no willingness to convert

Timeline: Days 1-5 (Week 1), parallel with Test 1.

Validation Test 3: Single-Entity Sufficiency (Week 1, embedded)

Method: Interview question embedded in Test 1

Script: During the mapping review, ask: "When you import data, do you ever need to import two types of records at once (e.g., Users and their Accounts in one file)? How do you handle that today?"

Success criteria:

• = 70% of admins report single-entity import as their primary need

• Multi-entity cases are rare or handled by sequential imports

Failure criteria:

• 40% of admins describe multi-entity import as a primary workflow

Timeline: Embedded in Test 1 interviews, Day 4-5.

7. Delivery plan + scope-change guardrails

Milestones (fit inside 4-week appetite)

Week 1: Foundation + Validation

• BE: File upload endpoint (single CSV, max 10 MB), basic CSV parsing (UTF-8), schema for entity-field mappings
• FE: Upload screen UI (drag-and-drop + file picker), admin sidebar entry point
• Design: Finalize mapping screen mockup, error-state designs
• Validation: Run WoZ Tests 1-3 (column mapping, file characteristics, single-entity sufficiency)
• Milestone gate: File uploads to server; WoZ results reviewed; mapping algorithm requirements confirmed

Week 2: Mapping + Validation Engine

• BE: Column auto-mapping engine (string similarity), validation engine (type checks, required fields, unique key detection), error report generation (JSON)
• FE: Column mapping screen (auto-suggestions + manual override dropdowns), preview table (first 10 rows)
• Milestone gate: Admin can upload a file and see auto-mapped columns with preview; validation engine returns row-level errors. Internal demo to team.

Week 3: Import Execution + Error Handling

• BE: Import execution (row-by-row insert/update via existing API), progress tracking (polling endpoint), error CSV generation, file cleanup (24-hr purge cron)
• FE: Validation summary screen (X valid, Y errors, Z warnings), error detail view, downloadable error CSV, progress indicator, confirm/cancel flow
• Milestone gate: End-to-end happy path works with a test file. Admin can upload, map, validate, review errors, confirm, and see results. Internal QA begins.

Week 4: Polish, QA, and Ship

• BE: Edge case hardening (empty files, single-row files, duplicate headers, max-row-count enforcement), performance testing with 5K-row files, security review (PII in logs, file storage)
• FE: Error/empty/loading states, in-app help text, success confirmation screen with link to records
• QA: Full regression pass, cross-browser testing (admin panel supported browsers), accessibility check on new screens
• Docs: Knowledge base article, release notes draft
• Milestone gate: Feature-complete behind admin permission flag. Staged rollout to 3-5 beta admins for 2-3 days before general availability.

Scope-change policy ("trade, don't add")

• Rule: Time is fixed at 4 weeks. Any new scope request must trade off an equal-or-greater amount of existing scope. No exceptions.
• Decision owner: Product Manager (DRI). Escalation: Engineering Manager.
• How to evaluate requests:
  1. Does this item affect the core happy path or the top hypothesis? If no, it's deferred.
  2. Can it be faked/manual for V1? If yes, defer the automation.
  3. What must be removed to make room? Name it explicitly before approving.
• What gets traded off first (default cut order):
  1. Edge case coverage (rare file formats, unusual data patterns)
  2. Advanced configuration (mapping templates, import settings)
  3. Polish (animations, onboarding tutorial, advanced help)
  4. Keep trust/safety intact (validation, error reporting, data integrity are last to be touched)
• Where requests go: A single "CSV Import - Scope Requests" section in the project tracker. Reviewed at Wednesday standup. No side-channel approvals via Slack/email.

8. Risks / Open questions / Next steps

Risks

Open questions (would change cut decisions if answered)

1. What entity types are admins most likely to import first? (Users? Products? Contacts?) This determines which field schemas to prioritize in auto-mapping and validation. Owner: PM. Deadline: Week 1.
2. Do we have real usage data on admin data-entry volume? (How many records/week are created manually?) This validates the demand assumption and informs success metric baselines. Owner: Data/Analytics. Deadline: Week 1.
3. Are there compliance requirements around import audit logging? (SOC 2, GDPR data processing records?) If yes, the deferred "audit log" may need to be promoted to a must-have. Owner: Legal/Compliance. Deadline: Week 1.
4. Is the existing REST API's per-row insertion rate fast enough for 5K rows? (Need a benchmark.) If not, we may need a bulk DB insert path, adding backend complexity. Owner: Backend lead. Deadline: Week 1, Day 3.
5. What is the admin panel's current file upload infrastructure? (Max size limits, storage location, CDN, etc.) May affect the upload implementation approach. Owner: Backend lead. Deadline: Week 1, Day 2.

Next steps (owners + dates)

Self-assessment: Quality gate

Checklist results

1) Appetite + decision checklist:

• Decision is explicit (ship) and has a DRI (PM, to be confirmed)
• Appetite is explicit (4 weeks, hard)
• Non-negotiable constraints are listed (privacy, data integrity, file purge, idempotency)

2) Hypothesis-first MVP checklist:

• Outcome is written in user terms ("import records in minutes instead of hours")
• 3 hypotheses are stated clearly (value, usability, trust)
• Success metrics + guardrails are measurable and defined
• Failure criteria are stated (in validation plan)

3) Minimum Lovable Slice checklist:

• Slice is end-to-end (upload -> map -> validate -> confirm -> done)
• Must-haves are short and fit the appetite
• Non-goals are explicit and defensible (11 items listed)
• Lovability elements increase clarity/trust (auto-mapping, dry-run preview)

4) Cut list checklist:

• Every cut/defer has a rationale tied to outcome/appetite
• Edge cases are handled explicitly
• Each deferred item has a "revisit when..." trigger
• No "just in case" scope without evidence

5) Validation plan checklist:

• Top 3 riskiest assumptions identified
• Method is fastest path to learning (WoZ in Week 1, parallel with build)
• Success and failure criteria defined in advance
• Timeline, audience, and script/flow are included

6) Scope-change guardrails checklist:

• "Trade, don't add" rule is clear
• Decision owner (PM) and escalation (EM) are defined
• Default trade-off order is defined
• Stakeholders know where requests go (project tracker section, reviewed at standup)

7) Finalization checklist:

• Includes Risks / Open questions / Next steps with owners and dates
• Assumptions are labeled (A1-A5) and reviewable
• A stakeholder can approve the slice async without a meeting

Rubric scores

This Scoping & Cutting Pack can be approved asynchronously. The team can begin execution in Week 1 with parallel validation and implementation tracks. The first scope checkpoint is end of Week 1 after WoZ results are reviewed.