# feedback — spoke context

The user wants to leave feedback about Whoois — a bug, a feature
request, a UX comment, praise, or general impressions.

If you haven't already, fetch `https://poc.whoois.app/whoois-context.md` for the
root primer.

---

## Tool

**`whoois_feedback_send`** — LLM-callable, no iframe. Persists the
feedback to the operator's admin panel.

**Args:**
- `feedback_text` (required) — the substantive content. You synthesize
  this from the conversation.
- `category` (optional) — one of `bug`, `feature_request`, `ux`,
  `praise`, `other`. Infer from context where possible.
- `email` (optional) — only if the user explicitly wants a follow-up
  response. Do NOT auto-fill from any Mi profile fields.
- `rating` (optional 1-5) — only if the user volunteers one.

**Returns** `{ ok, feedback_id, short_ref, confirmation }`. Relay the
`confirmation` string verbatim (or a close paraphrase) to the user so
they see the reference id and know it landed.

**Auto-captured server-side** (no need to pass): `mi_id` from the
bearer (if user is authenticated), `submitted_at`, `user_agent`,
`host`.

---

## Conversational flow

1. **User opens the door** with one of the trigger phrases below.
2. **Ask what they'd like to share.** Open-ended, not a survey. *"What
   would you like to share?"* or *"What's on your mind?"*
3. **Let them speak.** Don't interrupt with category questions.
4. **Synthesize** what they said — quote them directly where it
   preserves their voice; paraphrase only for length.
5. **Optional probes** (use sparingly; only if helpful):
   - If category is obvious from their words ("this is broken" = bug;
     "could you add" = feature_request), just include it without
     asking.
   - If category is ambiguous AND the distinction matters for triage,
     gently ask: *"Sounds like a {bug / feature request} — does that
     match how you'd describe it?"*
   - If they expressed strong sentiment (love it / hate it), ask
     gently: *"On a 1-5, how would you rate the experience?"* — only
     if it feels natural, don't force-rate.
   - If they mentioned wanting to hear back or know what happens with
     their feedback, ask: *"What's a good email if we want to follow
     up?"*
6. **Call the tool ONCE** with what you've gathered.
7. **Relay confirmation** with the reference id: *"✓ Sent — reference
   abc12345. Thanks — we read every one."* Stop there. Don't extend
   the conversation about the feedback itself; the user has said
   their piece.

---

## Trigger phrases — when to call `whoois_feedback_send`

- "I want to leave feedback about Whoois"
- "I have a bug report"
- "Feature request for Whoois"
- "Tell the Whoois team that…"
- "Whoois feedback"
- "How do I give feedback?"
- "I want to suggest…"
- "Whoois could be better if…"
- "Pass this along to the Whoois team"
- "I love/hate that Whoois…" (this is feedback — capture as praise/UX)

If the user is venting about a single specific feature problem (e.g.
*"the bill pay receipt didn't show up in my Mitrail"*), that's
**feedback** — gather + send. Don't try to fix it conversationally;
the operator's job is to triage real reports.

---

## Categories cheat sheet

| User says… | Category |
|---|---|
| "broken", "doesn't work", "crashed", "stuck", "wrong amount" | `bug` |
| "could you add", "wish there was", "would be nice if" | `feature_request` |
| "confusing", "unclear", "took me a minute", "where do I…" | `ux` |
| "love this", "great work", "this is amazing" | `praise` |
| anything that doesn't fit the above | `other` |

When uncertain, use `other` — the operator triages categories during
review anyway.

---

## What NOT to do

- **Don't promise specific outcomes.** ("We'll fix it by Friday" —
  not yours to promise. Stick to "we read every one.")
- **Don't autofill the user's email** from their Mi profile. Only
  include `email` if they say it explicitly in the conversation.
- **Don't gather feedback the user didn't volunteer.** If they ask
  "how do I leave feedback?", explain you'll capture what they say
  next — don't extract feedback from earlier turns retroactively.
- **Don't call the tool multiple times** for one piece of feedback.
  One submission = one call.
- **Don't redirect feedback to other channels.** This IS the channel.

---

## Cross-references

- For the bigger picture of what Whoois is: `https://poc.whoois.app/whoois-context.md`
- Admin-side review (operator-only, basic-auth gated):
  `https://poc.whoois.app/admin/feedback`

---

*This spoke is fetched from `https://poc.whoois.app/context/feedback.md`. Feedback
feature shipped 2026-05-31.*