Consultative Discovery and Requirements Gathering Questions

Clarifying questions (grouped)

• Platform & features

  • Which mobile platforms (iOS, Android, PWA)? Minimum supported OS versions?
  • Which features must be mobile-first (push notifications, camera, geolocation, background sync)?
  • Is feature parity with web required or a subset?

• Offline behavior & storage

  • Must the app work fully offline or partially? Which data/actions are critical offline?
  • Preferred client storage (SQLite, IndexedDB, secure storage)?
  • Conflict resolution policy for offline edits (last-write-wins, CRDT, merge UI)?

• Network constraints & reliability

  • Expected network conditions (high-latency, intermittent, metered)?
  • Max payload size and tolerance for retries/backoff?
  • Need for data minimization or delta-sync?

• Required APIs & auth

  • Which resources and operations are required (CRUD, streaming, file upload)?
  • Auth method (OAuth2, JWT, mTLS)? Token refresh strategy?
  • Do mobile clients need WebSocket/Push or long-polling?

• Performance & SLAs

  • Target API latencies (p95, p99) for interactive flows?
  • Bandwidth/CPU budget for mobile clients?
  • Acceptable sync window and freshness guarantees?

Minimal API contract (assumptions: mobile = iOS/Android + PWA; partial offline; OAuth2 JWT; delta-sync preferred)

• Endpoints:

  • GET /v1/items?since=ISO8601 — returns changed items since timestamp (delta sync)
  • POST /v1/items — create (returns full resource)
  • PATCH /v1/items/{id} — partial update with client_version
  • DELETE /v1/items/{id}
  • POST /v1/sync/conflict — submit conflict resolution if needed
  • POST /v1/upload — resumable file upload (supports chunked)

• Common headers:

  • Authorization: Bearer <jwt>
  • If-None-Match: <etag> for conditional GETs
  • X-Client-Version, X-Last-Sync: ISO8601

Example response for delta GET:

{
  "since":"2026-03-01T12:00:00Z",
  "items":[{"id":"123","data":{...},"updated_at":"...","deleted":false,"version":4}],
  "cursor":"opaque-cursor"
}

Assumptions & trade-offs

• Delta-sync + cursor reduces bandwidth vs full sync.
• JWT + standard OAuth simplifies mobile token flow; requires refresh endpoints.
• Conflict endpoint defers complex merge to server or UX, keeping client simple.
• Resumable uploads handle flaky networks at cost of extra implementation.

This list and contract let engineering estimate work, define storage/sync libraries, and scope MVP mobile capabilities.

Situation & goal clarification (immediate questions)

• What problem are we solving? (missing, outdated, inconsistent docs, low adoption, support load?)
• Who's the primary audience for the MVP? (internal devs, external third‑party integrators, mobile/web teams, SREs)
• Which APIs/endpoints are highest priority? (public REST endpoints, GraphQL schemas, webhooks, auth flows)
• What format/tech stack do we prefer? (OpenAPI/Swagger + static site, Postman collections, developer portal, README-first)
• Are there existing source artifacts (OpenAPI spec, annotated code, examples)?
• Timeline and sprint capacity? Stakeholders & approvers?

Target audience segmentation

• External integrators: quickstart, example requests/responses, auth, rate limits
• Internal backend devs: schema definitions, change log, internal best practices
• Platform engineers/SREs: observability, SLAs, error codes

Tooling preferences

• OpenAPI 3.0 spec as source of truth
• Swagger UI / Redoc for interactive docs
• Postman collection for runnable examples
• Docs-as-code in repo (markdown + CI validation)

Measurable success criteria

• Top 5 endpoints documented with OpenAPI + examples
• Interactive docs deployed to staging portal
• 90% of devs in target group can follow quickstart in <15 minutes (survey/task)
• Reduced “how to” support tickets by 30% in 4 weeks

MVP acceptance checklist

• OpenAPI spec created/updated for prioritized endpoints
• Quickstart tutorial (auth + one end-to-end call) with copy-paste examples
• 5 example requests/responses and error codes documented
• Interactive docs deployed to staging URL
• Owner/reviewers listed and sign-off completed
• CI validation ensures spec linting on PRs

This set of questions and deliverables scopes a focused sprint, aligns tooling with developer workflows, and sets measurable outcomes for the documentation MVP.

Clarifying questions (reveal hidden costs & implications)

• Scope & intent

  • What user problem does each approach solve, and what is minimum viable user outcome?
  • Which APIs/components change and who else depends on them?

• Technical debt & maintenance

  • What shortcuts does the quick fix introduce (workarounds, duplicate logic, config flags)?
  • Will the quick fix require future migrations or paid technical work to remove? Estimated effort?

• Risk & reliability

  • How do both options affect uptime, data consistency, observability, and rollback safety?
  • What test coverage and monitoring would be required for each?

• Schedule & business impact

  • Exact delivery timelines and milestones for both options.
  • What revenue, retention, or regulatory deadlines are impacted by delay?

• People & operational cost

  • Who will own post-launch cleanup? How many engineering hours per month expected?
  • Any hiring/training implications for the refactor?

Decision rubric (score 1–5 per criterion; weighted)

• User/business urgency ( weight 30% )
• Long-term maintainability & tech debt ( weight 30% )
• Risk to production ( weight 15% )
• Developer velocity impact ( weight 15% )
• Cost & resource availability ( weight 10% )

Score both options, compute weighted total; choose higher score unless business-critical deadline forces short-term sacrifice with mandated remediation plan.

Example assumptions and decision

Assumptions:

• Quick fix: 2 weeks dev, adds ~25% extra monthly maintenance (~20 hours/month), needs refactor in 12 months (estimated 4 sprint rewrite).
• Refactor: 8 weeks, reduces future dev time by 15%, eliminates known race condition, delays launch of a $200k quarter feature.

Apply rubric:

• Business urgency = 4 (can delay one quarter)
• Maintainability = quick 2, refactor 5
• Risk = quick 3, refactor 5
• Velocity impact = quick 3, refactor 4
• Cost = quick 5, refactor 2

Weighted totals -> refactor wins. Decision: accept delay for refactor, but add staged deliverables and feature flags to mitigate business impact. Include SLA for cleanup if quick fix chosen.

Situation & immediate goal
I’d act to stop further non‑compliant exposure while clarifying assumptions fast: which region, which cohorts, what data flows, and where enforcement must occur (client, server, CDN). With limited time I surface assumptions explicitly to stakeholders and the team.

Surface assumptions

• Assume affected users are identified by IP → risk of VPN/misclassification.
• Assume dataflow includes PII stored in service X and third‑party Y.
• Assume deadline prevents full legal review.

I’d document these in a one‑page decision log and attach to the ticket.

Immediate mitigations

• Deploy a temporary server‑side geo‑block for the affected region (protects server storage).
• Gate the feature behind a remote feature flag scoped by region + account risk group.
• Pause downstream exports/integrations to third parties for affected cohorts.
• Add monitoring/alerts for any attempted accesses from the region.

Scope work to achieve compliance

• Sprint 0: Legal confirmation + precise list of prohibited data operations.
• Sprint 1: Implement permanent geo‑aware authorization in API gateway, audit logs, and retention changes.
• Sprint 2: Update UI/UX messaging and consent flows; QA and penetration test.
  Estimate: MVT in 4–6 weeks; full compliance 8–12 weeks.

Stakeholder & customer communication

• Immediately notify: engineering lead, legal, security, product leadership, ops — include assumptions, mitigations, and rollback plan.
• Within 24 hours: customer‑facing note for affected region: “Feature temporarily disabled while we confirm privacy settings; no action required; contact support.”
• Weekly updates until compliance achieved; store decision log for audit.

This balances quick risk reduction with a scoped, auditable path to full compliance and minimal customer disruption.

Clarifying questions

• What are the business goals / KPI for the funnel (revenue, activation, retention)? Target conversion metric?
• What are the funnel stages and their definitions (explicit success events)?
• Who are the users (segments, cohorts) and expected traffic volumes?
• What platforms/browsers/SDKs are in scope and existing analytics stack (Snowflake, BigQuery, Segment, Amplitude, GA, etc.)?
• Are there existing user identifiers (logged-in ID, anonymous ID)? How is identity resolved across devices?
• SLAs: latency for reporting (near‑real time vs daily)?
• Compliance constraints (PII, GDPR, consent) and retention policies?
• Ownering teams: who instruments front-end/back-end and who owns data modeling?

Logged assumptions for estimation

• Assume stable product definition of funnel stages.
• Assume one canonical user_id plus anonymous_id mapping available.
• Assume existing event pipeline (e.g., Segment -> warehouse) reusable.
• Assume medium traffic (X events/day) — will revise with real numbers.
• Assume no major schema migrations required.

Minimal required instrumentation

• Unique user identifier on every event (user_id or session_id).
• Distinct, immutable event names for each funnel step with timestamps.
• Context: page/url, product_id, platform, campaign metadata.
• Server-side event for purchase/commit to avoid client loss.
• Consent flag where required.

Rollout plan & data validation

1. Design & spec (2–3 days): event catalog, schemas, ownership, test cases.
2. Instrument (1–2 sprints): front-end + back-end events; include feature flags for staged rollout.
3. Smoke tests (dev): synthetic events verifying schema, user_id mapping, timestamps.
4. Staging validation (3–5 days): replay events to warehouse; verify counts, deduplication, ordering.
   • Validation checks: event volume parity vs expected, funnel step sequentiality, user path sanity, nulls in key fields.
5. Canary production (week): enable for X% traffic; monitor metrics and error rates.
6. Full rollout + monitoring: dashboards for funnel conversion, data freshness, and alerting for schema drift.

This plan balances speed and data quality; update estimates once traffic and existing pipeline details are confirmed.