# Volleyboard — initial idea doc

> Status: napkin sketch. This is a vibe doc, not a plan. We're capturing the
> spark and stacking up questions to flesh out later. Nothing here is decided.

---

## The dream (in one breath)

Short-term project management / issue tracking, reimagined as a **game of
volleyball**. One team is generally **doing the work**; the other is
**requesting, reviewing, and approving** it. Work moves like a ball: it gets
**served**, **passed** between teammates, and **hit back over the net**. You feel
each touch. There are little **dopamine-inducing bounce sounds**, maybe a
**score**, and the score quietly nudges everyone to keep the **rallies short** —
because a long rally means an issue that keeps bouncing around instead of getting
put away.

The standard case: we built a website for a client, and now we're walking it
together — the client reviews and reports issues, we fix and send them back,
they approve. But it should scale up to running an **entire web project end to
end** as one long, watchable game.

---

## Why volleyball actually fits

- **There's a net.** Work genuinely has two sides with a real boundary between
  them: the people asking for work and the people making it. A ticket "going over
  the net" is exactly what a hand-off between client and dev *feels* like.
- **You rally, you don't just hand off.** Real work bounces around a side before
  it's ready to send back. Volleyball already has a word for that: the pass, the
  set, the spike.
- **Touches are limited.** Volleyball's 3-touch rule is a built-in "don't sit on
  the ball" mechanic. That maps perfectly onto the thing we actually want:
  **keep things moving, don't let issues rot.**
- **It's a rally, not a war.** Both sides ultimately want a good game — a rally
  that flows. That's the right emotional tone for client work: playful rivalry,
  shared success, not adversarial ticket-warfare.

---

## The court

```
        DOERS' SIDE                      net                 REQUESTERS' SIDE
  (build / fix / deliver)                 |               (request / review / approve)
                                          |
        Rian · Adi            ⇄  serve / spike ⇄            Erin · Tracy
   (+ Adi's crew behind)                  |              (+ Erin's crew behind)
```

- A **serve** starts a rally: someone reports an issue / makes a request.
- A **rally** is the life of that item — every pass and hit until it's put away.
- **Putting it away / a clean resolution** ends the rally. (Who "scores" and what
  a point *means* is a juicy open question — see Scoring below.)

---

## The roster (our real teams)

**Requesters / reviewers (client side)**
- **Erin** — lead on the client side; the one who serves and ultimately approves.
- **Tracy** — *in-between*. Kind of on our side, kind of on Brentwood's. A
  utility player who can line up on either side of the net. (Volleyball has this
  too — think a libero / floating specialist.)
- **Ian**, **Terra** — Erin's bench: content + review support, not directly in
  the rally, but feeding Erin.

**Doers (dev side)**
- **Rian** — lead on our side; talks to Erin across the net.
- **Adi** — plays next to Rian, and *also captains his own sub-team*.
- **Zeina**, **Rahman**, **Stevan** — Adi's juniors. Any of them can pick up a
  ball Adi passes back; whoever's open takes it.

The interesting part: **this isn't two flat teams of N.** It's teams with
**benches and sub-teams**, and the ball can dip into a sub-team and come back out
without the other side ever seeing those touches.

---

## The big idea: nested courts (everyone sees their own game)

This is the part worth protecting. **The same item is a different game depending
on who's looking at it.** Everyone plays on *their own local court*, against the
neighbors directly in front of them.

Think of the whole path of an item as a **chain of nets**, but each person only
really perceives the net right in front of them:

```
[Ian] –net– [Erin] ═NET═ [Rian] –net– [Adi] –net– [Zeina]
   content     client  ║  our    internal   Adi's
   feed        lead    ║  lead    hand-off   crew
                       ║
              the "official" net everyone scores on
```

- **Zeina** sees a two-person court: Adi on one side, her on the other. She's
  just trying to have a clean rally with Adi.
- **Adi** sees *two* courts at once: one where he passes to his juniors, and one
  where he rallies with Rian.
- **Rian** sees Erin across the big net and Adi as a teammate beside him.
- **Erin** sees Rian across the net and Ian/Terra as her bench.

So the **fractal / rally-of-rallies** idea: one issue "over the big net" might
contain a dozen little rallies nobody upstream ever counts. When Adi sends it
back to Rian, Rian has no idea (and doesn't need to) how many times it bounced
around Zeina, Rahman, and Stevan first.

**Design consequence:** the board is **perspective-relative**. Same underlying
item, rendered as *your* court, with *your* neighbors, showing *your* touches.

---

## A worked rally (Erin's serve)

Straight from the founding vision — one issue, one full trip:

1. **Ian** gives Erin some input (a pass on the client bench).
2. **Erin** serves it over the big net to **Rian**.
3. **Rian** passes to **Adi** (our side sets it up).
4. **Adi** passes it into his crew — **whoever's open** (say **Rahman**) picks it up.
5. Rahman does the work, passes back to **Adi**.
6. **Adi** passes to **Rian**.
7. **Rian** hits it back over the net — *maybe via an automated rule* — to **Erin**.
8. **Erin** passes to **Ian**, who actually resolves it.
9. Resolution **trickles back up**: Ian → Erin, and **Erin (the original server)
   marks it resolved.**
10. **Everyone sees it as resolved** — but each person only ever watched their own
    slice of the rally.

That whole journey is *one point* at the big-net level, and *many little rallies*
underneath.

---

## Bounces, touches, and keeping rallies short

Borrow volleyball's touch limit as the core tempo mechanic:

- Something like **"2 bounces on your side, then it has to go back over the net."**
  In the example: Rian → Adi (bounce 1), Adi → Rian (bounce 2), Rian → over the
  net (bounce 3, the hit). Meanwhile Adi's crew may have bounced it a dozen times
  on *their* sub-court — sub-courts might have their own touch budget.
- The point isn't to be strict — it's to make **stalling visible and a little
  uncomfortable**, and quick returns **feel good**. A ball that's been held too
  long could start to wobble, glow, drop — some gentle "hit me!" pressure.
- **Aces & clean returns:** an issue resolved in a single touch (no rally needed)
  is an **ace** — extra dopamine.

Open question: is the touch limit a *rule* (enforced) or a *vibe* (nudge)? Lean:
**vibe first.** Nudges, not blockers.

---

## Scoring, sounds, dopamine

The sensory layer is not decoration — it's the product.

- **Sounds:** a soft *bounce* on a pass, a satisfying *thock* on a spike over the
  net, a *whistle* on a fresh serve, a bright *ding* on a resolve. Short, tactile,
  skippable/mutable.
- **Motion:** the ball visibly travels between avatars; hits over the net arc.
- **Score — the open design question.** Volleyball scoring is competitive, but
  here **both sides want the project to win.** So what does a "point" mean? Some
  candidates to argue about:
  - *Rally efficiency:* short rallies score well; balls that bounce forever cost
    the whole game. (Score = shared health, not us-vs-them.)
  - *Co-op vs the backlog:* the real "opponent" is entropy / the pile of open
    issues, and the two human teams are actually **playing together against the
    board.** Friendly-rivalry flavor on top, co-op underneath.
  - *Streaks & flow:* consecutive clean returns build a combo/flow meter.
  - Careful: **scoring can go toxic fast** (turns into a performance-review
    dashboard). Keep it playful, keep it team-level, avoid ranking individuals.

---

## The whole project as a match (sets, milestones, "complete")

The review app only ever saw the *middle* of a project — the review-and-fix
rally. Volleyboard should hold the **whole arc**:

- **Match = the whole project**, kickoff to "we call it complete."
- **Sets = milestones / phases** (discovery, build, content, review, launch). You
  win a set by hitting a milestone; the match by shipping.
- **Timeline / scoreboard** shows progress across the whole game — which set
  you're in, how the rallies are going, how close "complete" is.
- **"Complete"** is the real win condition — the final whistle. Everything else is
  keeping good rallies going until you get there.

---

## The pre-game (the part the review app missed entirely)

Before the rallies start, there's a whole **warm-up / roster phase** the current
app has no concept of:

- Initial requests: access, credentials, intros, questions, team-forming.
- Gathering requirements — most of it up front, but with a **steady trickle**
  arriving all through the match.
- Think of it as **"getting on the court"**: line up the roster, agree on the
  net, sort out who's serving. It's messy, it's mostly one-directional
  (requests inbound), and it deserves its own space — maybe a "warm-up board" or
  a pre-match checklist that keeps producing the occasional new ball mid-game.

These are *sort of* like today's "General Issues," but framed as **wrangling the
project into existence** rather than tracking defects in an existing thing.

---

## What we keep from the review app (the good starting point)

The review app is a strong base to lift from:

- Fast, responsive, single-page / spreadsheet-feel board.
- Statuses + review states + automations (status drives review, etc.).
- Notes / threaded comments / pasted screenshots.
- @mentions + live notifications (realtime).
- Presence ("who's on the court right now").
- Features + General Issues as separate lanes.

Volleyboard reuses the *bones* (Supabase + realtime + a snappy board) and rethinks
the *shell* around the volleyball metaphor.

---

## Decisions parked for the build

- **Auth = BW Auth (Pattern B) from day one.** Volleyboard will "Sign in with BW"
  rather than roll its own (the review app used Supabase auth). This also gives us
  **"View As"** for free via the standard `bw_view_as.py` drop-in
  (`/srv/system/id-auth/app-auth/VIEW-AS.md`) — privileged users can render the board
  as another player (support/QA, "what does Erin see?"), read-only by default, with
  oversight on the BW hub. Deliberately NOT retrofitted into the review app; it lands
  here instead.

---

## Open questions to flesh out (next time)

1. **Co-op or competitive?** Is the other team an opponent or a partner? (Lean:
   co-op against the backlog, friendly-rivalry flavor.)
2. **What is a "point"?** And can we score without it curdling into surveillance?
3. **Perspective-relative rendering:** how literally do we build "everyone sees
   their own court"? One shared item, many views — how far does that go?
4. **Touch limit:** enforced rule or gentle nudge? What's the budget, and do
   sub-courts get their own?
5. **How visible are sub-teams across the net?** Does Erin see that Adi's crew
   touched it, or just that "the dev side has it"? (Privacy of the rally.)
6. **Tracy the in-betweener:** first-class concept (floating players who pick a
   side per rally) or edge case?
7. **Automated rules as a "player":** Rian hitting it back "via an automated
   rule" — is automation a teammate on the court? A ball-machine?
8. **Sets & matches structure:** how heavy? A full project scoreboard, or a light
   progress ribbon?
9. **Sound & motion budget:** how much juice before it's annoying at work? Mute
   defaults, per-user.
10. **Name.** "Volleyboard" is the working title and it's good. (Others to reject
    later: Rally, Overnet, Set Point, Bump, Sideout.)

---

## The one-liner to keep us honest

**Volleyboard: run a whole project like a good volleyball rally — serve, pass,
send it back, keep it short, and everyone's playing their own little game on the
way to the same win.**