Ty_Tech/geolocal-io
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: restore full strategy depth; add UC-01 and UC-02

Browse Source 
- Expand CANONICAL_STRATEGY with retrieval substrates, commerce chairs,
  multi-path discovery, ingestion, quality/decommission, trust bar
- Rebalance platform vs SSP (portal is activation, not the company)
- Add principal-PM use cases for endpoint auto repair and tourism board
- Update product docs and README entry points
This commit is contained in:
VPS admin
2026-07-18 06:00:26 +00:00
parent 3f9c86f823
commit 9478aaa22e
12 changed files with 680 additions and 188 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/product/use-cases/README.md
+20 -2
View File
@@ -1,5 +1,23 @@
# Use cases
Canonical use cases (Bob’s Garage, destination board, etc.) will land here as structured product specs.
Canonical use cases for product, engineering, and GTM. These are operating specs, not marketing blurbs.
Until then, narrative examples remain in the strategy and archive; do not treat the archive as the product spec.
| ID | Name | Model | Status |
|----|------|-------|--------|
| [UC-01](./uc-01-endpoint-auto-repair.md) | Endpoint activation — independent auto repair | Model 1 | Spec |
| [UC-02](./uc-02-intermediate-tourism-board.md) | Intermediate activation — destination tourism board | Model 2 | Spec |
## How to write more of these
Use the same template as UC-01/UC-02:
- Problem and context
- Primary actor and stakeholders
- Preconditions
- Main success scenario (numbered)
- Alternate and exception paths
- Success metrics
- Explicit out of scope
- Open questions
If a use case only restates strategy prose, it is not ready. If it cannot drive a sprint ticket, it is not ready.
docs/product/use-cases/uc-01-endpoint-auto-repair.md
+155
View File
@@ -0,0 +1,155 @@
# UC-01 — Endpoint activation: independent auto repair shop
**Status:** Spec
**Business model:** Model 1 — Endpoint enablement
**Primary surface:** Platform MCP + Self-Service Portal (activation)
**Priority:** P0 (shapes Priority 0 engineering)
---
## 1. Problem
An independent auto repair shop (example: a transmission-focused garage in a suburban market) is increasingly invisible when consumers ask AI assistants for help. The shop may have a basic website and a Google listing, but those surfaces rarely expose specialization, services, availability, or a clean booking path in a form assistants can use. When an engine shortlists and then inspects the site, it finds ambiguity. The shop loses the recommendation moment without ever knowing it happened.
---
## 2. Desired outcome
Within one session, the owner (or a trusted family member / local web person) can:
1. Create a geolocal presence for the shop
2. See how an assistant would currently understand them
3. Attach a simple discovery pointer on their site
4. Verify the live MCP answers correctly for their services
5. Understand what to fix next
6. Start receiving basic interaction reporting
The shop becomes machine-legible and bookable through assistants **without** buying a customer-facing chatbot product.
---
## 3. Actors
| Actor | Role |
|-------|------|
| **Owner or operator** | Decision maker; may not be technical |
| **Delegate** (optional) | Daughter, office manager, or local web partner implementing the pointer |
| **AI assistant** (external) | ChatGPT, Gemini, Claude, Copilot-class systems requesting local help |
| **End consumer** | Person asking the assistant for a repair |
| **geolocal platform** | Hosted MCP, ingestion, portal, telemetry |
---
## 4. Preconditions
- Shop has some public web presence (even a thin site) or can publish a single page that can hold a pointer
- Shop can accept appointments (phone calendar is a weak start; Cal.com or equivalent is preferred for fulfillment path)
- Operator can complete a web signup flow
- For full fulfillment demo: a booking link or integrated booking endpoint exists or can be created during onboarding
---
## 5. Main success scenario
1. **Arrive** — Operator opens geolocal.io and starts “add my business.”
2. **Genre selection** — They identify as automotive / auto repair. The experience switches to auto-repair language and examples (not generic SMB fluff).
3. **Identity capture** — Name, location, website URL, phone, hours if known.
4. **Initial scrape / reflection** — Platform fetches public site content and shows what it can already see: services mentioned, specialties, gaps, confusion.
5. **Value simulation** — Portal shows a phone-and-chat style simulation: an assistant recommends this shop for a Korean-transmission style job, lists services it believes are offered, and proposes an appointment path (e.g. Thursday 3:00). Operator gets the aha: pre-qualified, in-scope demand.
6. **Pointer install** — Portal gives a tiny attachment (well-known file, link tag, or equivalent multi-path option) pointing to the hosted MCP for this business. Operator or delegate installs it.
7. **Preflight** — Portal runs a live test against the MCP (not a scripted mock). If services, specialty, hours, or booking path are wrong or missing, failures are explicit.
8. **Correct** — Operator edits portal fields and/or site content; preflight re-runs until critical checks pass.
9. **Upstream guidance** — Portal explains that MCP only helps after engines can find the site; offers a short findability checklist and optional partner referral.
10. **Go live** — Endpoint is marked live. External agents that discover the pointer can call structured tools.
11. **Report** — On a weekly cadence (or first short digest sooner), operator sees interaction counts, top intents, and gaps (“agents asked about warranty; you have no answer”).
---
## 6. Alternate paths
| ID | Trigger | Behavior |
|----|---------|----------|
| A1 | Operator is non-technical | Portal emphasizes one-click copy steps; offers partner handoff without blocking signup |
| A2 | Website is nearly empty | Simulation still runs from portal-entered data; scrape reflection shows hard gaps; go-live may be limited until minimum content exists |
| A3 | No online booking yet | Fulfillment path degrades to “call/book link pending”; portal prioritizes installing Cal.com (or peer) rather than inventing a booking engine |
| A4 | Delegate implements pointer | Owner still owns account; delegate gets install instructions only |
| A5 | Promo content changes (e.g. July 4 oil-change special) | Owner updates site or portal fields, re-runs preflight, confirms special appears in test harness |
---
## 7. Exception paths
| ID | Trigger | Behavior |
|----|---------|----------|
| E1 | Preflight fails repeatedly | Block “fully live” status; show ranked fixes; do not claim AI-ready |
| E2 | Pointer installed on wrong domain | Detect mismatch; fail preflight with plain-language error |
| E3 | Chronic low helpfulness after go-live | Quality loop opens coaching; after threshold, endpoint can be quarantined or decommissioned (see strategy quality rules) |
| E4 | Business is not local service | Soft reject or route out of ICP during genre/identity step |
---
## 8. Functional requirements (product)
- Genre-aware onboarding for auto repair
- Site scrape + human-readable reflection
- Simulation that is obviously about *external* AI, not “your new chatbot”
- Multi-path pointer generation (not a single fragile convention)
- Live MCP preflight in browser
- Editable structured profile (services, specialty, hours, booking link, story)
- Reporting of agent interactions and failed questions
- Partner referral option when site work exceeds self-serve
## 9. Data the MCP must support for this genre (minimum)
- Identity and location
- Hours
- Services list with plain-language descriptions
- Specialization signals (e.g. transmissions, European/Korean makes)
- Booking path (link or orchestrated booking later)
- Story / trust copy (owner, tenure, guarantees if present)
- Optional: emergency vs scheduled, estimate vs fixed-price notes
Exact schema lives in engineering; this list is the product contract for “auto pack v1.”
---
## 10. Success metrics
| Metric | Definition | Early target |
|--------|------------|--------------|
| Time to first preflight | Signup → first live MCP test | Under 30 minutes for a motivated operator |
| Preflight pass rate | Share of signups that pass critical checks within 7 days | Track; improve weekly |
| Pointer verified | Discovery attachment confirmed live | Required for “live” badge |
| Weekly active endpoints | Live endpoints with ≥1 agent or preflight interaction | Leading indicator |
| Owner-reported clarity | “I understand what this does” after simulation | Qualitative; interview first 20 |
---
## 11. Out of scope for UC-01
- Building a consumer marketplace or destination site
- Replacing the shop’s booking vendor
- Full SEO agency services
- Multi-location franchise admin
- Guaranteeing a specific assistant will recommend the shop (we make them recommendable; engines still choose)
- Model 2 intermediate aggregation (see UC-02)
---
## 12. Dependencies
- HTTP multi-tenant MCP
- Ingestion/scrape pipeline
- Portal application
- Auto-repair genre pack v1
- Cal.com (or equivalent) for fulfillment path
- Quality policy for quarantine/decommission
---
## 13. Open questions
1. Minimum content bar before “live” vs “limited live”?
2. Which pointer formats do we support on day one vs later?
3. Do we require booking link for go-live, or only for “bookable” badge?
4. Who performs first decommission decision — product ops rule or human review only?
docs/product/use-cases/uc-02-intermediate-tourism-board.md
+160
View File
@@ -0,0 +1,160 @@
# UC-02 — Intermediate activation: destination tourism board
**Status:** Spec
**Business model:** Model 2 — Intermediate enablement
**Primary surface:** Intermediate MCP + member onboarding (reuses Model 1 endpoint mechanics)
**Priority:** P1 for full dashboard; pilot can start as soon as Model 1 endpoints exist
---
## 1. Problem
A destination tourism board (example: a coastal city visitor bureau funded partly by lodging tax) is supposed to promote local experiences and member businesses. In practice, its website is a human-readable brochure: lists, categories, PDFs, event calendars. AI assistants treat that class of site as a **weak discovery surface** — useful for confirming that a place or business exists, weak for evaluating specialization, availability, or booking.
The board has budget it is expected to spend on promotion, and often limited internal confidence about how to spend it for the AI era. Member businesses pay dues and still remain invisible to assistants. The brochure rack in the hotel lobby still does more immediate work than the website does for agentic visitors.
---
## 2. Desired outcome
The board can:
1. Stand up a **destination-level MCP** that helps assistants understand the place and route to member services
2. Onboard a first cohort of members onto geolocal endpoints (directly or via staff/partners)
3. See simple evidence of value: member attach rate, agent hits, category demand
4. Justify the pilot against lodging-tax / visitor-experience goals
5. Convert members from pilot access to paid endpoints over time
The board stops being only a link list and becomes a **high-signal intermediate** in the AI discovery and evaluation path.
---
## 3. Actors
| Actor | Role |
|-------|------|
| **Board director / marketing lead** | Buyer; cares about destination performance and politics of members |
| **Board staff** | Day-to-day member onboarding and content hygiene |
| **Member business** | Local service or experience provider (charter, bike rental, repair, spa, etc.) |
| **Visitor** | Consumer asking an assistant for things to do / local help while traveling |
| **AI assistant** | External engine using intermediate + member signals |
| **geolocal platform** | Intermediate MCP, member endpoints, reporting |
---
## 4. Preconditions
- Board has authority (or pilot permission) to run a technology pilot for members
- Identifiable first verticals or member shortlist (e.g. charters, activities, essential services)
- Ability to communicate with members (email list, meetings, onboarding workshop)
- geolocal can host member endpoints (UC-01 mechanics available, even if rough)
- Legal: basic pilot terms and data use understanding
---
## 5. Main success scenario
1. **Pilot framing** — Board agrees the goal is AI visitor helpfulness and member discoverability, not “another directory redesign.”
2. **Destination profile** — Staff provide place identity, priority categories, seasonal notes, and member list.
3. **Intermediate MCP live** — Platform exposes a destination endpoint assistants can use to understand the place and list structured member options by category.
4. **Member cohort invite** — Board invites 20–100 members into onboarding (workshop, email, or staff-assisted).
5. **Member activation** — Each member completes UC-01-style activation (scrape, pointer, preflight) with destination context pre-associated.
6. **Aggregation** — Intermediate MCP only surfaces members that meet minimum quality/live bars (not every unpaid legacy listing by default).
7. **Visitor path** — A visitor asks an assistant for a charter, e-bike rental, or emergency phone repair in the destination; assistant can use intermediate signal and/or member MCP rather than a thin brochure page alone.
8. **Board reporting** — Dashboard (or pilot report) shows members live, category coverage, interaction counts, and top unmet intents.
9. **Conversion** — After pilot window, members move to paid tiers; board retains intermediate subscription or partnership terms.
10. **Expansion** — Board adds categories or a second wave of members; quality bar remains enforced.
---
## 6. Alternate paths
| ID | Trigger | Behavior |
|----|---------|----------|
| A1 | Board wants white-glove only | Staff or geolocal-assisted onboarding for first cohort; self-serve still available |
| A2 | Chamber of commerce instead of tourism board | Same intermediate pattern; funding story shifts from lodging tax to member value / economic development |
| A3 | Members already on booking platforms | Keep those booking paths; intermediate still supplies discovery/evaluation structure |
| A4 | Low technical capacity at board | Start with spreadsheet-fed member import + staff login; full dashboard later |
---
## 7. Exception paths
| ID | Trigger | Behavior |
|----|---------|----------|
| E1 | Member fails preflight | Exclude from intermediate “recommended” set until fixed; still visible to staff as incomplete |
| E2 | Member harms destination helpfulness | Quarantine from intermediate aggregation; board notified |
| E3 | Political pressure to list everyone regardless of quality | Product keeps a “directory dump” mode separate from “AI-recommended set”; do not poison the high-signal path |
| E4 | Procurement delay | Keep SMB self-serve in market; treat board as parallel track, not a gate on all GTM |
---
## 8. Functional requirements (product)
- Destination (intermediate) entity with categories and member associations
- Intermediate MCP tools: place overview, category browse, member resolve, seasonal notes
- Member onboarding that reuses endpoint activation
- Quality gating between “listed” and “AI-ready / aggregated”
- Board-facing report or dashboard: attach rate, hits, intents, gaps
- Pilot-friendly admin (invite, status, export)
## 9. What the intermediate MCP must do (minimum)
- Answer “what is this place good for?” in structured form
- List live members by category with deep links to member MCP identity
- Avoid inventing services the member cannot support
- Prefer members with passing preflight and fresh data
- Expose contact/booking paths only when member endpoint provides them
The intermediate is a **bridge with signal**, not a second Yelp and not a passive HTML list.
---
## 10. Success metrics
| Metric | Definition | Early pilot target |
|--------|------------|--------------------|
| Members invited | Cohort size | 20–100 |
| Members live | Passed critical preflight + pointer verified | ≥40% of invited within pilot window |
| Intermediate queries | Agent or test harness hits on destination MCP | Weekly growth |
| Category coverage | Priority categories with ≥1 live member | Board-defined must-have set complete |
| Board satisfaction | Willingness to renew / expand | Explicit yes/no at pilot review |
| Member conversion | Live members → paid after pilot | Track; optimize after first pilot |
---
## 11. Out of scope for UC-02
- Replacing the board’s full CMS or membership CRM
- Building a consumer destination marketplace branded as geolocal
- Guaranteeing tourism lift numbers in season one
- National multi-board enterprise packaging before one pilot works
- Owning lodging, flights, or car rental (Airbnb/Kayak space)
---
## 12. Dependencies
- UC-01 endpoint activation working for at least one tourism-relevant genre
- Intermediate MCP routing and aggregation rules
- Pilot agreement template (legal)
- Reporting (even CSV/manual is acceptable for first pilot)
- Quality policy shared with Model 1
---
## 13. Funding and sales notes (GTM, not engineering)
- Pitch against **mandated or expected promotion spend**, not against random software budget
- Language: visitor experience, member value, AI-era discoverability, stewardship of lodging-tax intent
- Proof: before/after member AI-readiness and intermediate query evidence
- Risk to name honestly: procurement speed; mitigate with short pilot and parallel SMB motion
---
## 14. Open questions
1. First destination market(s)?
2. Does the board pay, members pay, or both during pilot?
3. Hard quality gate for aggregation from day one, or soft gate with warnings?
4. Branding: geolocal-powered vs fully white-labeled board experience for v1?