source: .forge/discovery/meeting-notes/2026-09-03-requirements-gathering-questions.md · generated — edit the markdown, not this file

Empire Teas CRM — Requirements-Gathering Question Set

Meeting date: 2026-09-03 Prepared by: Biseni (with Claude assisting) Status: Draft working agenda — not issued to the client. Sources: raw session notes, cross-checked against .forge/project-prd-signals.md (live OQs), .forge/client/open-questions.md (already issued to Empire, Q1–Q9), .forge/client/dependencies.md (the seven blocking inputs), and .forge/project-prd.md.

How to use this

Every question carries a ref so you can tell at a glance whether it is new ground or a chase:

Mark Meaning
(OQ-nn) Already a live open question in project-prd-signals.md
(issued Qn) Already asked of Empire in writing in client/open-questions.md — chase the answer, don’t re-ask from scratch
(dep n) Already on the issued dependency register, client/dependencies.md § 3
NEW Not tracked anywhere yet — needs logging as an OQ after the meeting
🔴 Changes something already locked (an Architecture Decision or an accepted commercial commitment) — needs an explicit, recorded answer, not a nod
⚠️ Development is waiting on it now

Where we already have a working position, it is stated as Our default. Ask for a confirm-or-correct against the default rather than a decision from a blank page — it is faster and gets better answers.


Part 0 — Decisions that change something already locked

Take these first. Each one either reverses a decision in the CLAUDE.md Architecture Decisions table or touches the accepted proposal, so each needs a named person’s answer on the record.

D1. Microsoft-only login — dropping Google and email/password. 🔴 NEW

The note says: keep Microsoft, do not add Google, do not add username/password.

  • What it changes: AD #5 is a locked decision for dual-path login — OAuth2 (Google and Microsoft) plus local email/password, both mapping to one User entity. Dropping two of the three paths is a reversal, not a preference, and needs recording as a new AD that supersedes it.
  • What to confirm in the room: is every person who will ever need access — sales reps, Tea Room, Executive, Administrators, and every capture-app user on the trade-show floor — inside Empire’s Microsoft 365 tenant with a licensed account? A single contractor, agent, or shared floor device outside the tenant re-opens the local-password path, and it is far cheaper to keep it in scope now than to add it in November.
  • What we gain if the answer is yes: no password storage, no reset flow, no set-password screen, no credential-strength policy — a real reduction in F5’s surface and in security burden.
  • Our default: proceed MS-only, and log the reversal as an AD.

D2. Is the shared info@ inbox inside the accepted V1 scope? 🔴 (OQ-54, issued Q6)

Our internal PRD and architecture treat it as first-class and the issued dependency register asks Empire which shared addresses to connect — but the accepted proposal scopes mailboxes only as “each user connects their own Microsoft 365 mailbox” and names no shared inbox.

  • Why it matters: this is a commercial call (Altrium management), not a documentation fix. Either the client-facing PRD gets corrected and re-issued, or the shared inbox becomes a change request.
  • Don’t resolve this in a requirements meeting — flag it, and route it. See also Part 4.

D3. The capture app does more than we scoped, and less. 🔴 (OQ-55, issued Q9) ⚠️

The POC already ships things F36 never scoped (campaign scoring lens, bulk pile-splitting, camera-roll import, pre-show exhibitor CSV targeting, expo-intelligence campaigns, duplicate detection) and is missing two things F36 requires: badge QR scanning and offline-tolerant queued upload — both verified absent.

  • Why it matters: the POC has been demoed. Features Empire has seen working would be deliberately left out of V1 unless they say otherwise. This is the single most likely source of a UAT surprise.
  • Our default: F36 ships exactly as written; the five extras are post-V1; QR + offline queueing are net-new build inside F36.

D4. Two environments or three — and is a client-visible UAT environment expected? 🔴 (OQ-49)

The issued proposal contradicts itself: §11 promises “development, staging, and production” at handover; five places in Appendix A say two, and price a third as an unpurchased add-on.

  • What we do today: two permanent environments (development + production), with a temporary UAT environment stood up per acceptance round and destroyed after it. Development never doubles as UAT.
  • Ask: does Empire expect a permanent staging environment at handover? If yes it is +cost/month, an extra promotion tier, and a CI/CD shape change — a change request, not an oversight.

Part 1 — Login, Microsoft identity, and the Azure app registration

Q1. Azure app registration — who owns it, and can we get it moving this week? ⚠️ NEW

This is the item most likely to cost calendar time through back-and-forth with Empire and Dialog, so settle it in the room with a named owner and a date. Five parts:

  1. Who creates the app registration — Empire’s IT (or Dialog, if they administer the tenant), or Altrium against a delegated admin role?
  2. Single-tenant or multi-tenant? Our default: single-tenant — only Empire’s directory can sign in, which is the tighter posture and matches an internal tool.
  3. One app registration or two — dev and production? Our default: two, so dev credentials and redirect URIs never touch production and either can be revoked independently.
  4. Redirect URIs — we need the CRM URL and the capture-app URL registered (they are separately hosted at separate addresses), for each environment. Blocked on Part 8’s domain answer.
  5. The permission list and one-time admin consent (dep 4) — read/write mail, send mail, read/write calendar, read/write contacts, shared-mailbox access. The administrator approves once for the whole organisation; after that each person connects their own mailbox with one click, no IT ticket per person.

Bring to the meeting: the exact permission list and the consent URL, so it can be actioned live rather than promised.

Q2. Confirm the sign-in sequence. NEW

Our intended flow: Microsoft sign-in → Microsoft validates → the CRM checks the user against its own allow-list → session issued. A valid Empire Microsoft account is necessary but not sufficient — the person must also exist as a CRM user with a role.

  • Ask: is that the behaviour they want, or should any tenant member be auto-provisioned on first sign-in? (Auto-provisioning has no answer for what role a self-provisioned user lands in — it needs a default-role rule, or it is not viable. See also OQ-51.)
  • Our default: allow-list. A tenant account alone does not grant CRM access.

Q3. Session management. NEW

Session lifetime, idle timeout, “remember me”, and whether signing out of Microsoft should sign the user out of the CRM. On the capture app specifically: a rep on an exhibition floor should not be re-authenticating between cards — a long-lived session there is a usability requirement, not a lapse.

  • Our default: server-side sessions (Spring Session JDBC), a working-day idle timeout on the CRM, a notably longer one on the capture app.
  • Falls away if D1 is confirmed: password reset, set-password, password storage, strength policy.

Q4. Microsoft SDK / API surface. Internal — for information only

Which Microsoft libraries we use (MSAL for sign-in, Graph SDK for mail/calendar/contacts) is our call and needs nothing from Empire. Raise it only if their IT has a constraint on which app types or authentication flows are permitted in the tenant.


Part 2 — Roles and privileges

Q5. A confirmed privilege breakdown for all six roles. ⚠️ (OQ-53, issued Q1, dep 3)

Already asked in writing and still outstanding — chase it, and if possible walk it in the room. The specific gaps are Tea Room and Executive / Management, which exist in prose and were never mapped per-resource.

  • Tea Room: pricing screens only, or also read access to accounts, deals and quotes?
  • Executive / Management: read-only across everything, including quotes and buyer contact details?
  • Our default: Tea Room = weekly bulk pricing only; Executive = read-only everywhere.

Useful framing: ask what each role can do in Pipedrive today and start from that — see Q6.

Q6. What roles and permission sets exist in Pipedrive today? NEW

Their current Pipedrive permission sets are the most reliable statement of what people actually need, and a far better starting point than designing in a vacuum. Capture this during the Pipedrive audit if not in the meeting.

Q7. Managing Director — a role, or a permission? (OQ-53, issued Q3)

Largely settled by AD #26: F7 checks the named permission APPROVE_SUB_FLOOR_QUOTE, never role == ADMIN, so who holds it is configuration, not code. What still needs Empire’s confirmation:

  • Our plan is that the MD gets an Administrator account, and any Administrator can approve a below-floor quote. Two consequences they should agree to knowingly: any future Administrator inherits that ability, and an Administrator can also change the margin floor and then approve against the lower figure. Both are recorded in the audit trail; neither is prevented.
  • If they would rather restrict approval to named people, that is a settings change, not a rebuild.

Q8. Administrator — user management and business configuration, one screen or two? NEW

Administrators hold two quite different jobs: user management (create users, assign roles, deactivate) and business data configuration (pipelines and stages, custom fields, margin floor, reference data). Ask whether Empire sees these as one Administrator or as separable — some organisations want the person who adds users to have no ability to change the margin floor.

  • Our default: one Administrator role holding both, because AD #26 means splitting them later is a configuration change rather than a code change.

Q9. Can one person hold more than one role? (OQ-51, issued Q2)

Plausible at 10–20 users — someone who is both Tea Room and Sales Manager.

  • Our default: one role per person.

Part 3 — Onboarding and offboarding

Q10. How does an Administrator add a user? (OQ-51, issued Q2)

If D1 lands as Microsoft-only, the invite-email-with-password-link option disappears and this simplifies considerably: an Administrator creates the CRM user record against a Microsoft identity, and the person signs in with the account they already have.

  • Confirm: is the role a mandatory field at creation, or set afterwards? Our default: mandatory — an account cannot exist role-less.
  • Confirm: may an Administrator change a role later, and what happens to that user’s in-flight approvals and owned records?

Q11. Deactivation and offboarding. (OQ-51, issued Q2)

When someone leaves: what happens to their accounts and deals — pass to their manager, reassign manually, or leave in place? And their mailbox connection is released on deactivation.

  • Our default: records stay put; an Administrator reassigns them. Deactivate, never delete — the audit trail must keep resolving their name.
  • Also confirm: who may create an Administrator, and last-admin protection (the system must refuse to deactivate the final Administrator).

Q12. The first user — how does the very first Administrator exist? NEW

Nobody can log in to create the first account. Options: seed it in a database migration against a named Empire email address, or a one-time bootstrap on first run.

  • What we need in the room: the named person and their Empire email address to seed. This is a five-minute answer that blocks the first real login on every environment.
  • Our default: seeded via migration, one named Administrator, per environment.

Part 4 — Email

Q13. info@empireteas.com — is it a mailbox or a distribution list? ⚠️ NEW (sharpens OQ-52)

This is the load-bearing question in this section and it has a technically different answer each way.

  • A shared mailbox has its own storage, can be synced through Graph, and conversations can be read, replied to, and attached to CRM records. This is what the design assumes.
  • A distribution list has no mailbox — it fans mail out to members’ personal inboxes. There is nothing to sync. If info@ is a DL today, connecting it to the CRM means Empire converting it to a shared mailbox (or creating one alongside), which is an Empire-side action with a lead time.
  • Ask: which is it today, how does it behave in Pipedrive today, and are there other shared addresses (per office, per market)? Naming them now is free; discovering them at UAT is rework.

Dependent on D2 — settle whether it is funded scope before designing it.

Q14. Who can see the shared inbox, and how are its inquiries assigned? (OQ-52, issued Q6)

  • Visibility: every rep, Administrators only, or a designated triager? Personal mailboxes are private-by-default (Pipedrive parity); the shared one has no stated rule.
  • Assignment: round-robin, an unassigned queue, or a fixed owner?
  • Surface: does an info@ inquiry appear in the Inbox only, or also raise a lead in the triage queue? (Note: the client-approved prototype’s Inbox is a single flat thread list with no mailbox selector — so there is no approved design for this yet.)

Q15. Conversation visibility on the customer record. NEW

Confirm the rule the notes describe: a conversation one rep has with a buyer is recorded against the customer record, and other users viewing that record can see the history.

  • Ask precisely: is that every user with access to the record, or the owner plus managers? And does it apply to the whole thread or only messages the rep chose to link?
  • Why it matters: this is the one rule that decides whether a rep’s mailbox feels private. Get it wrong and it is either a privacy complaint or a “why can’t I see what was promised” complaint.
  • Our default: email sent/received is scoped by record visibility — if you can see the deal, you can see its linked correspondence. Unlinked personal mail stays private.

Q16. Reply, Reply-all, and Forward from inside the CRM. NEW

The PRD’s F20 covers sync, send, templates and tracking, but never states these three explicitly.

  • Confirm all three are expected in V1, and that a Forward carries attachments.
  • Also confirm: CC/BCC on CRM-sent mail is already captured as a requirement from the 2026-07-16 meeting — worth re-confirming it survives into these three.

Q17. Three test accounts with working mailboxes. ⚠️ (dep 4)

Already asked. Chase: three test.*@empireteas.com Microsoft 365 accounts, each with a live mailbox — two acting as sales reps, one as a sales manager, at least one with access to the shared inquiries mailbox. Without these, who-can-see-what is proven against a simulation instead of Empire’s real setup. They can be deleted after go-live.


Part 5 — Audit logs

The PRD names an audit trail for record create/update/delete, stage moves, pipeline configuration, quote-pricing approvals, and AI actions. Everything below is unspecified.

Q18. Is authentication in scope for the audit log? NEW

Login, logout, failed sign-in attempts, session expiry. Not currently in the PRD’s audit list.

  • Our default: yes — record login and logout. Failed attempts are worth capturing too, and cheap.

Q19. Deletes — soft or hard? NEW

An audit trail that records “record deleted” but cannot show what was deleted is of limited use.

  • Our default: soft-delete for core records, so the audit entry still resolves to something.

Q20. Who can read the audit log, and where does it live? NEW

  • Reader: Administrators only, or Executive/Management too? Is it a screen in the app, or an operational artifact the team queries?
  • Storage: the notes ask “DB and logs” — these are different things with different properties. Our position: the business audit trail lives in the database (queryable, joins to users and records, survives log rotation, and is what an auditor is shown); application logs go to CloudWatch for operations and are not the audit trail. Confirm nobody is expecting one to substitute for the other.
  • Retention: how long must audit records be kept? Nothing in the PRD states a period.
  • Our default: DB-backed audit trail, Administrator-visible, retained for the life of the system.

Part 6 — The capture app (PWA)

Start with D3 — the scope divergence — then work through these.

Q21. Badge QR — is it needed, and which format? ⚠️ (OQ-55)

F36 requires it; the POC does not have it (no QR/barcode library, no BarcodeDetector).

  • Ask: do the trade shows Empire attends actually issue scannable badges, and what is encoded — a plain URL, a vCard, an organiser-specific ID that is meaningless without their lookup service, or a proprietary format needing the organiser’s own hardware?
  • Why it matters: “scan the QR” ranges from trivial (vCard) to impossible (organiser-locked ID). We cannot size it without knowing which. Ask for a photo of a real badge from a recent show.

Q22. Multi-card scanning. NEW

Reps collect a stack, not one card. Two different features hide behind “multi-card”:

  • Several cards in one photo (a pile on a table), split automatically — the POC already does this.
  • Rapid sequential capture — shoot ten cards in a row, process the queue afterwards.

Ask which one they mean, and whether it is V1 or a nice-to-have. Both are outside F36 as written.

Q23. Offline behaviour. ⚠️ (OQ-55)

Exhibition Wi-Fi is unreliable. F36 requires offline-tolerant queued upload; the POC does not have it (no IndexedDB, no background sync — its “works offline” banner refers only to the app shell, so a capture taken with no signal is currently lost).

  • Confirm this is a real requirement and not theoretical — if the halls Empire exhibits in have reliable connectivity, this is a candidate to descope.

Q24. Who logs in to the capture app, and how? NEW (interacts with D1)

  • Ask: one shared login for the stand, or each rep individually? Does the rep who captured a lead need to be recorded against it?
  • Ask: Microsoft sign-in on the capture app too, or something lighter for floor use?
  • Our default: individual Microsoft sign-in with a long session, so capture attribution works.
  • Note: if a shared stand device is wanted, that is a shared account outside the per-person model and it re-opens D1.

Q25. CSV upload — what, from where, and what do they expect it to do? NEW

The note is broad. There are two unrelated things called CSV upload:

  • In the capture app: the POC’s pre-show exhibitor list import — load the organiser’s attendee list, target and rank it before the show. This is a POC extra, outside F36.
  • In the CRM: F23’s spreadsheet import — leads, contacts, organisations, deals, products, activities, with column mapping and duplicate resolution. This is in V1.

Ask: which one do they mean, what file do they actually receive from show organisers (get a sample), and what do they want to happen to it?

Q26. Manually adding a lead in the capture app. NEW

Beyond scanning — can a rep type a lead in by hand? (No card offered, a conversation with no card, a correction to a bad scan.)

  • Our default: yes for correcting a scan; ask whether a from-scratch manual entry is needed.

Q27. Book the Thilina walkthrough. ⚠️

Get a date. The POC is the most complete artifact on this project and the least documented for the rest of the team. Cover: what is built and verified, the AI card-read pipeline and its prompts, the API contract shape, and — most useful — what he would do differently. Note the POC’s Python/Supabase/Fly backend does not port (AD #19–#23); it is a reference for pipeline, contract and prompt design only.


Part 7 — Pipedrive

Q28. Book the Pipedrive audit session. ⚠️ (dep 2)

Still the highest-value item on the dependency register — one guided session answers roughly a dozen open design questions and de-risks the migration more than any other single act. Needs a full export (all record types, custom fields, files, users) or administrator access for a walkthrough.

The questions it answers on its own are listed in Appendix B — none of them need Empire to prepare.

Q29. Migration mapping — what actually comes across? (OQ-6, OQ-26)

Walk the list explicitly and get a yes/no per entity: leads, deals, organisations, contacts, products, pricing, notes, activities, files, email history, custom fields, saved filters, automations.

  • The sharper question: what do they need in the new system versus what is simply in Pipedrive? Migrating dead data is cost with no benefit. Ask for a cut-off — “deals closed before X don’t matter”.
  • Also: how long has Pipedrive been in use, and are activities logged consistently enough to be worth migrating at all?

Part 8 — AWS, domains and DNS

Q30. AWS account handover. ⚠️ (dep 1)

Chase. Empire creates and hands over the management account; Altrium then creates the development and production accounts beneath it under AWS Organizations — isolated environments, consolidated billing, still one bill. Region US East (us-east-1). See D4 on whether a third permanent environment is expected.

  • Flag the lead time: SES starts every new account in restricted sending mode, and production sending access has an approval delay. The earlier the account exists, the earlier that clock starts.

Q31. Domain names and DNS access. ⚠️ (dep 5)

Three things, and all three have propagation lead time:

  1. The address the CRM lives at.
  2. A second address for the capture app (separately hosted, its own URL).
  3. DNS access to add SPF, DKIM and DMARC records for the sending domain.

Blocks Q1, because redirect URIs on the Azure app registration need the final addresses.


Part 9 — ERP handoff

Q32. IFS, or the new ERP — and what needs to pass to it? (OQ-2, issued Q8)

V1 ships the manual handoff document regardless; automated integration is separately priced and follows once an API is confirmed.

  • Confirm: IFS is the current ERP; is a replacement still coming, and when?
  • Ask for: whether IFS exposes usable APIs or an export format, and a sample of the document or export the ERP team actually needs on a won deal — one real example is worth an hour of discussion.
  • Ask: should anything come back (order, shipment, invoice status)?

Part 10 — Entity model and configuration

These feed the data model directly. Precise answers here save the most rework.

Q33. Buying Standard. NEW (sharpens the F26 model)

The bulk pricing model is built around it and is DDL-verified, but validating it against Empire’s real price list is an outstanding client dependency (dep 7).

  • Ask: how is a buying standard identified and named? Is the list stable or does it change seasonally? Who may add one? What is its relationship to a grade — is a standard a grade, or a grade-plus-quality-band?
  • Ask for the actual weekly price list. One real spreadsheet settles most of this section.

Q34. Price precision. NEW

Genuinely unasked, and cheap to get wrong permanently.

  • How many decimal places on a unit price, and is that consistent across bulk and private-label?
  • What currency, and are prices ever held in more than one? If so, who sets the rate and when is it fixed — at quote time, or at won?
  • What unit is the price per — kg, lb, or per pack?
  • Rounding: at line level or at total? Rounded half-up?
  • Why it matters: this is a database column type. Changing it later means a migration across every price, cost, quote line and history row.

Q35. Customer. NEW

  • Is the buying entity always an organisation, or do individual buyers exist?
  • Do they deal with buying houses or agents who purchase for several end buyers? If so, does the CRM need to model that relationship, or is the agent simply the customer?
  • Do customers have parent/subsidiary or per-market branches that must roll up for reporting?
  • Our default: flat organisations with contacts beneath them; no hierarchy in V1.

Q36. Certificates — held by the product, the batch, or the company? ⚠️ (OQ-9, issued Q4, dep 6)

Already asked and still outstanding — the one item on the issued list with no safe fallback. Buyer certification requirements are in a spreadsheet (confirmed); the product side is not.

  • The new dimension in the notes is the sharp one: is a certification held by a product, by a batch/lot, or by the company/estate? These are three different data models, and the mismatch check behaves differently in each. A batch-level answer in particular means the CRM needs batch identity it does not currently model.
  • Ask for a sample of the real data, in whatever form it exists — spreadsheet, QC records, paper.

Q37. Calendar and contact sync. NEW (confirmation only)

Two-way sync of calendar and contacts through Microsoft Graph is in V1 (F21, F22).

  • Confirm two-way is wanted, not one-way.
  • Ask: should CRM activities appear on the rep’s Outlook calendar as real events, and should meetings created in Outlook come back? Any calendars that must not sync (personal, shared team calendars)?

Part 11 — Demos and sign-offs to book

Q38. CRM and capture-app flow demo — sign-off. ⚠️

Walk the approved prototypes with Empire and get an explicit sign-off on the flows. This is what protects against a UAT-stage “that isn’t what we pictured”.

  • CRM prototype: .forge/design/prototypes/crm/ (needs a local server and network).
  • Capture app snapshot: .forge/design/prototypes/pwa/ (self-contained — double-click it).
  • Pair this with D3 — show them what the POC does that V1 will not include, in the same session, while it is cheap to discuss.

Q39. Sessions to get in the diary before you leave the room.

Session With Blocks
Pipedrive audit / walkthrough ⚠️ Empire admin + Dinil ~12 open questions + migration design
Capture-app walkthrough ⚠️ Thilina F36 sizing, OQ-55
Azure app registration ⚠️ Empire IT / Dialog All login work, both apps
Prototype flow sign-off Empire sales leadership Design lock
Price-list working session Tea Room F26 model validation
Certification data session QC / Kavi Amali F9 — no fallback

Appendix A — Already asked in writing, still outstanding

From .forge/client/open-questions.md, issued 2026-08-21. Chase these rather than re-asking — and note which have been answered since, so the issued document can be updated.

Issued Topic Our ref Urgent
Q1 What each role may see and do (Tea Room, Executive) OQ-53 ⚠️
Q2 Adding a user; what happens when someone leaves OQ-51
Q3 Who signs off a below-floor quote — confirm our plan OQ-53 / AD #26
Q4 Where product certifications are kept OQ-9 ⚠️
Q5 Where the product/SKU list lives OQ-27
Q6 How the shared inbox should work OQ-52
Q7 When a deal should be flagged as going quiet OQ-12 / OQ-13
Q8 Confirming IFS and what passes to it OQ-2
Q9 The capture app does more than we scoped, and less OQ-55 ⚠️

Appendix B — Answered by the Pipedrive audit, not by Empire

Do not spend meeting time on these — they come out of the account itself. Listed so nobody asks Empire to prepare answers they do not need to.

Pipeline mix and deal counts (OQ-1) · lead-vs-deal usage (OQ-5) · migration record volumes (OQ-6) · tea grades in use (OQ-7) · volume units and pack formats (OQ-8) · private-label and bulk cycle times for stale thresholds (OQ-12, OQ-13) · inbound languages (OQ-17) · active user count (OQ-22) · paid add-ons in use (OQ-23) · templates and sequences (OQ-25) · custom fields, saved reports, automations, integrations (OQ-26) · product/SKU source (OQ-27) · weighted forecasting and rotting thresholds (OQ-28) · sales goals usage (OQ-29) · current pipelines and stage names (OQ-30) · what they would most miss (OQ-41 — ask live during the walkthrough, it gets a richer answer in conversation).


After the meeting

  1. Log everything marked NEW that got an answer into project-prd-signals.md as resolved, or as a new OQ if it did not.
  2. D1 (Microsoft-only login), if confirmed, needs a new row in the CLAUDE.md Architecture Decisions table superseding AD #5 — a reversal must be recorded, not assumed.
  3. D2 and D4 are commercial and route to Altrium management, not into a spec.
  4. Write the debrief as 2026-09-03-requirements-clarification.md in this folder, matching the 2026-08-03 precedent — dated primary records of client answers rank high in the source-trust order.

Generated from .forge/discovery/meeting-notes/2026-09-03-requirements-gathering-questions.md by .claude/lib/render-docs-html.js. Markdown is canonical.