# ShelfShare: idea and stakeholder notes

> Fictional demo. ShelfShare, its maker *Lanternworks* and every person, product and API below are invented.
> Statement labels (method §105): **[FACT]** source fact · **[AI]** AI-generated analysis · **[DECISION]** human decision ·
> **[HYPOTHESIS]** · **[REC]** recommendation · **[HISTORY]** historical rationale.

## The idea (week 1)
ShelfShare is a neighbourhood book-swap app. People list the books they have finished, find books nearby and swap them in person.
Today the swap itself happens off-app: in a chat, by guessing a meeting place, and sometimes by nobody showing up.

**Feature under discussion:** *Swap & Handoff*, which takes a swap from "I want that book" to "books exchanged" inside the app.

## Problem
- **[FACT]** In a 2-week in-app survey of 412 active members, 61% of agreed swaps never happened. The most common reasons were "couldn't agree where/when" (38%) and "the other person didn't show" (27%).
- **[FACT]** Support tickets mention "met a stranger at their house and felt uneasy" 9 times in one quarter.
- **[HYPOTHESIS]** If the app arranges where and when to meet and confirms the handoff, more agreed swaps will be completed.

## Desired outcome
- At least 70% of accepted swaps are completed (baseline 39%).
- No meeting at a private address is required.
- Both members can see that the swap happened, and each book moves to its new owner's shelf.

## Stakeholders
| Who | Perspective | Wants | Worries |
|---|---|---|---|
| **Community lead (Ana, product)** | Growth through trust | Fast, friendly swaps; less back-and-forth | Feels bureaucratic |
| **Trust & safety (Ravi)** | Member safety | Meetings in public places; no exposed home locations; a way to report | Location data leaking; harassment |
| **Platform engineering (Jo)** | Feasibility, cost | Reuse existing services (accounts, places, messaging, notifications) | New real-time infrastructure; battery drain |
| *(member interviews, 6 people)* | Day-to-day use | "Just tell me where and when"; "show me who's close right now" | "I don't want people to see where I live" |

**[AI]** The interviews contain one tension: "show me who's close right now" vs "don't show where I live". It is logged as open question Q1.

## Initial use cases
- UC-1 Browse books near me
- UC-2 Request a swap (offer one of my books)
- UC-3 Owner accepts or declines
- UC-4 Arrange the handoff (where and when)
- UC-5 Confirm the handoff with a code; the books change shelves
- UC-6 Cancel or no-show
- UC-7 Nothing nearby (empty state)
- UC-8 Service error or timeout

## Open questions
- Q1 Live proximity vs location privacy (Ana vs Ravi). → resolved by the restructure, see `decision-log.md`
- Q2 Does a swap always need a book in return? → v2 adds swap credits