# 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) | # | Item | Keep / Cut / Defer | Why (tie to outcome/appetite) | Risk impact | "Revisit when..." trigger | |---|---|---|---|---|---| | 1 | Single CSV upload + file picker | **Keep** | Core entry point of the flow; required for any import | None | -- | | 2 | Auto-suggested column mapping | **Keep** | Key usability win; directly validates hypothesis #2 | None | -- | | 3 | Pre-commit validation + error CSV | **Keep** | Non-negotiable trust requirement; validates hypothesis #3 | None | -- | | 4 | Preview of first 10 rows | **Keep** | Low effort, high trust signal; part of "dry run" lovability | None | -- | | 5 | Progress indicator (polling-based) | **Keep** | Prevents admin anxiety during processing; low effort | None | -- | | 6 | Update-or-create via unique key | **Keep** | Essential for re-imports; prevents duplicate records | None | -- | | 7 | XLSX / JSON support | **Cut** | Adds parsing complexity and testing surface; CSV covers the primary use case | Low -- admins can "Save As CSV" from Excel | When > 20% of admins request non-CSV formats in feedback | | 8 | Non-UTF-8 encoding support (Shift-JIS, ISO-8859, etc.) | **Defer** | Rare for our user base; hard to detect reliably; significant testing effort | Medium for international admins -- mitigate with clear "UTF-8 required" messaging | When we expand to markets where non-UTF-8 CSVs are common (Japan, parts of EU) | | 9 | Multi-file / batch upload queue | **Cut** | Significant UI + backend complexity; single file covers the core job | Low -- admins can run sequential imports | When admins report importing > 5 files/session regularly | | 10 | Saved mapping templates | **Defer** | Nice-to-have for repeat importers; adds state management complexity | Low for V1; becomes important at high-frequency usage | When > 40% of admins import weekly or more often | | 11 | Scheduled / recurring imports | **Cut** | Completely different architecture (cron, notifications, retry logic); out of appetite | Low for V1; this is a "v2 or API" feature | When admins request automated syncs from external systems | | 12 | Import undo / rollback | **Defer** | High complexity (soft-delete, transaction logs); pre-commit validation mitigates risk | Medium -- a bad import requires manual cleanup. Mitigate with strong validation and "dry run" preview | When import volume > 10K rows/import or when data-sensitivity requirements increase | | 13 | Real-time progress via WebSocket | **Cut** | Polling is sufficient for files < 5,000 rows (< 60s processing); WebSocket adds infra complexity | Negligible for V1 file sizes | When import processing time exceeds 2 minutes regularly | | 14 | Import audit log / history | **Defer** | Useful for compliance but not required for V1 value validation | Low for V1; increases for regulated customers | When compliance/audit requirements are formalized or enterprise tier launches | | 15 | API-based (headless) import | **Cut** | Different product surface entirely (auth, rate limits, docs); does not validate admin UX hypothesis | None for V1 -- we're testing the UI flow | When 3+ customers request programmatic import for integrations | | 16 | Advanced data transforms in-UI | **Cut** | Scope explosion risk; admins can prep data in Excel before upload | Low -- "prep in Excel" is an accepted workflow | When discovery shows admins consistently struggle with data prep | | 17 | Multi-entity-type CSV import | **Cut** | Requires complex schema detection and routing; single-entity is the standard pattern | Low -- admins understand "one import per type" | When a dominant use case requires multi-type import (e.g., Users + Roles) | | 18 | Concurrent import protection | **Defer** | Edge case where two admins import to the same entity simultaneously; unique-key handling partially mitigates | Medium for data integrity in rare cases. Mitigate with advisory locking or a warning | When admin team size > 5 or when import frequency is high | | 19 | Large file support (> 10 MB / > 50K rows) | **Defer** | Requires streaming, chunked processing, background jobs; not needed for 90% of V1 use cases | Low for V1. Clear error message for oversized files. | When > 10% of uploads hit the size limit | | 20 | In-app onboarding tutorial | **Cut** | In-app help text + KB article is sufficient; tutorial adds design/eng cost | Negligible -- the flow is 5 steps with clear labels | When task completion rate is below 50% | **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 | Risk | Likelihood | Impact | Mitigation | |---|---|---|---| | Column auto-mapping accuracy is too low for a good UX | Medium | High -- mapping step becomes tedious, killing adoption | WoZ Test 1 in Week 1; pivot to guided manual mapping if < 60% accuracy | | Import processing is too slow for files near the 5K-row limit | Medium | Medium -- admin waits > 2 min; may abandon or retry | Performance test in Week 3 with 5K-row files; set a hard 5-min timeout with a clear message; defer to background jobs if needed | | PII exposure through temp file storage or error logs | Low | High -- compliance/security incident | Security review in Week 4; file purge cron; scrub PII from error messages; don't log row content | | Concurrent imports by multiple admins cause data conflicts | Low | Medium -- duplicate or conflicting records | Defer full concurrency protection; add advisory "another import is in progress" warning if detected via simple DB lock | | Team underestimates validation engine complexity (type checking, edge cases) | Medium | Medium -- Week 2-3 scope pressure | Keep validation rules simple for V1 (required, type, unique key, max length). Defer advanced rules (regex, cross-field, conditional). | | Admins expect XLSX support from day one | Medium | Low -- friction, not a blocker | Clear "CSV only (UTF-8)" messaging on upload screen; provide a "How to export CSV from Excel" link | ### 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) | Action | Owner | Due | |---|---|---| | Confirm DRI and team allocation | Engineering Manager | Before Week 1 starts | | Recruit 5-8 admins for WoZ validation tests | Customer Success / PM | Week 1, Day 1-2 | | Answer open questions 1-5 above | PM / Backend lead / Legal | Week 1, Day 3 | | Run WoZ Test 1 (column mapping) + Test 2 (file characteristics) | PM + 1 engineer | Week 1, Day 3-5 | | Review WoZ results and confirm/adjust MLS | Team (standup) | End of Week 1 | | Begin implementation (Week 1 milestone) | Engineering team | Week 1, Day 1 | | Internal demo of mapping + preview flow | FE + BE | End of Week 2 | | Security review of file handling and PII exposure | Backend lead + Security | Week 4, Day 1-2 | | Beta rollout to 3-5 admins | PM + QA | Week 4, Day 3-4 | | Ship to general availability (behind admin permission) | Team | Week 4, Day 5 | --- ## Self-assessment: Quality gate ### Checklist results **1) Appetite + decision checklist:** - [x] Decision is explicit (ship) and has a DRI (PM, to be confirmed) - [x] Appetite is explicit (4 weeks, hard) - [x] Non-negotiable constraints are listed (privacy, data integrity, file purge, idempotency) **2) Hypothesis-first MVP checklist:** - [x] Outcome is written in user terms ("import records in minutes instead of hours") - [x] 3 hypotheses are stated clearly (value, usability, trust) - [x] Success metrics + guardrails are measurable and defined - [x] Failure criteria are stated (in validation plan) **3) Minimum Lovable Slice checklist:** - [x] Slice is end-to-end (upload -> map -> validate -> confirm -> done) - [x] Must-haves are short and fit the appetite - [x] Non-goals are explicit and defensible (11 items listed) - [x] Lovability elements increase clarity/trust (auto-mapping, dry-run preview) **4) Cut list checklist:** - [x] Every cut/defer has a rationale tied to outcome/appetite - [x] Edge cases are handled explicitly - [x] Each deferred item has a "revisit when..." trigger - [x] No "just in case" scope without evidence **5) Validation plan checklist:** - [x] Top 3 riskiest assumptions identified - [x] Method is fastest path to learning (WoZ in Week 1, parallel with build) - [x] Success and failure criteria defined in advance - [x] Timeline, audience, and script/flow are included **6) Scope-change guardrails checklist:** - [x] "Trade, don't add" rule is clear - [x] Decision owner (PM) and escalation (EM) are defined - [x] Default trade-off order is defined - [x] Stakeholders know where requests go (project tracker section, reviewed at standup) **7) Finalization checklist:** - [x] Includes Risks / Open questions / Next steps with owners and dates - [x] Assumptions are labeled (A1-A5) and reviewable - [x] A stakeholder can approve the slice async without a meeting ### Rubric scores | Category | Score | Rationale | |---|---|---| | 1. Decision + appetite clarity | 2 | Decision (ship), DRI (PM), appetite (4 weeks hard), and constraints are all explicit | | 2. Outcome + hypothesis quality | 2 | User-centric outcome; 3 falsifiable hypotheses with clear validation targets | | 3. Metrics + guardrails | 2 | Measurable success metrics (completion rate, time-to-import, adoption %); guardrails have thresholds (0 corruption, < 5% tickets, < 10% latency impact) | | 4. MLS coherence | 2 | End-to-end 6-step flow; must-haves are minimal; 11 explicit non-goals; 2 lovability elements tied to trust | | 5. Cut list rigor | 2 | 20 items with keep/cut/defer decisions; each has rationale, risk impact, and revisit trigger | | 6. Validation plan strength | 2 | Targets top 3 unknowns; WoZ runs in Week 1 without building the system; success/failure criteria pre-defined | | 7. Delivery plan realism | 2 | 4 weekly milestones with specific tasks per role; milestone gates defined; beta before GA | | 8. Scope-change guardrails | 2 | "Trade, don't add" policy; decision owner + escalation; default cut order; single intake channel | | **Total** | **16/16** | | --- *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.*