# brand-taxonomy

The seven customer-complaint categories the swarm uses across every brand. Held constant across tenants so brand-sentry and trend reporting can compare apples to apples; brands cannot rename them, but they can disable any category from their dashboard view.

| Key | Label | What it covers | Sentinel phrases |
|---|---|---|---|
| `cleanliness` | Cleanliness | Floors, bathrooms, counters, food prep area, table tops, exterior. | "dirty", "sticky", "smelled", "filthy", "grime", "bathroom" |
| `wait_time` | Wait time | Time to be seated, time at the counter, drive-thru wait, online order ready time, response to inquiries. | "waited", "took forever", "slow", "still waiting", "drive thru" |
| `staff` | Staff | Friendliness, attentiveness, knowledge, rudeness, indifference. Includes manager interactions. | "rude", "ignored", "didn't care", "shrugged", "manager", "attitude" |
| `hours` | Hours | Closed when sign said open, posted hours wrong on Google, holiday hours not posted, closing early. | "closed", "open", "sign said", "hours", "wasted trip" |
| `product` | Product | Quality, freshness, taste, accuracy of order, portion, presentation. | "stale", "cold", "wrong", "missing", "tasted", "burnt", "undercooked" |
| `price` | Price | Value perception, pricing fairness, hidden fees, surprise charges, surcharges. | "expensive", "overpriced", "ripoff", "charged me", "surcharge" |
| `access` | Access | Parking, accessibility, signage, finding the place, drive-thru layout, mobility. | "couldn't find", "no parking", "accessible", "wheelchair", "signage" |

## How agents use this

- **review-aggregator** can optionally tag a review with one or more topics (max 3) using the sentinel phrases above as starting hints; topics are not invented outside this list.
- **escalation-router** uses topic severity to break ties on 3-star reviews. Cleanliness and staff are higher severity than price or access in our default model. Brands can adjust per their style.
- **response-drafter** uses the matched topic to anchor the acknowledgement ("we hear you on the wait" / "we hear you on the cleanliness"). Generic acknowledgements without a topic match feel off.
- **brand-sentry** rolls up topic counts weekly and surfaces clusters in the brand digest.

## When to add a new category

Only if the brand-sentry digest shows a meaningful cluster of reviews that none of the seven categories fits. Adding a category is a CL with thought: it ripples into every brand's reporting baselines.

Do not add a category for one brand's edge case. Brands can use their `response-style.md` `notes` field to capture brand-specific topic nuance.