grokbot_ty
5ac84b6ca5
Root REVIEW.md synthesizes geo-lead structure + SEO Desk research flags (lanes, fan-out ceiling, platform confirm/flag table, weak contradictions). Mechanical README map + BUSINESS_PLAN branch label for planning-selfserve-audit. No product contradictions closed.
184 lines
13 KiB
Markdown
184 lines
13 KiB
Markdown
# Review package — planning-selfserve-audit
|
||
|
||
**Repo:** Ty_Tech/geolocal-io
|
||
**Review branch:** `planning-selfserve-audit`
|
||
**Tip at package write:** `8337408f5b8ea1414d322bafa0ff33dbaeb48a96` (re-verify after this commit)
|
||
**Primary SoT:** [`docs/SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md`](docs/SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md)
|
||
**Strategy spine:** [`docs/BUSINESS_PLAN.md`](docs/BUSINESS_PLAN.md) §1 North Star
|
||
**Conventions:** [`docs/CONVENTIONS.md`](docs/CONVENTIONS.md) · [`docs/writing-rules.md`](docs/writing-rules.md)
|
||
**Parallel (non-SoT):** [`docs/ALTERNATE_BUSINESS_PROPOSAL.md`](docs/ALTERNATE_BUSINESS_PROPOSAL.md) · [`docs/research-brief.pdf`](docs/research-brief.pdf)
|
||
**Field / API evidence (Core 3):** [`docs/product/genre-packs/SOURCES.md`](docs/product/genre-packs/SOURCES.md)
|
||
|
||
## Goal
|
||
|
||
Make this branch review-ready so Ty can approve without re-litigating. Decisions and open flags live in-repo here. No product closures invented in this file: contradictions are **FLAG**ged for Ty.
|
||
|
||
## SoT pointers
|
||
|
||
| Layer | File | Owns |
|
||
| :--- | :--- | :--- |
|
||
| Product architecture | CONCEPT | Remediation stack, fan-out honesty, lanes, genre parents, phases |
|
||
| Strategy / GTM / wedge | BUSINESS_PLAN | North Star intent, Discovery foundation / Core 3, owner workflow, MCP distribution |
|
||
| Parallel thesis (non-SoT) | ALTERNATE + research-brief.pdf | Action-plan / warehouse framing; denser aggregator evidence |
|
||
| Core 3 field/API only | SOURCES + core3-field-map | Do not treat as deep edit URL inventory for ranks 1–14 |
|
||
|
||
Amend CONCEPT in place only. Evidence under `docs/evidence/`. No twin PLAN/NOTES/BRIEF beside CONCEPT. Do not merge or kill ALTERNATE. No force-push to `main`.
|
||
|
||
## Requirements (what “done enough to review” means)
|
||
|
||
- [ ] Mission readable without jargon: help owners get AI to recommend them; MCP = pipe not product; industry graph = Northstar, not v1
|
||
- [ ] Scoreboard explicit: Presence + Recommendability
|
||
- [ ] Problem = black box of NAP/category copies; claim once → correct outward
|
||
- [ ] Solution still labeled architect-not-built: audit findings → correction tickets; held multi-platform verification as moat
|
||
- [ ] Stakeholder verify / prove-the-shop-is-theirs treated as first-class pain (not optional)
|
||
- [ ] Lane model present: Lane A umbrellas (Data Axle, Localeze, Foursquare) + Lane B per-platform majors
|
||
- [ ] Every material claim either cited or marked BLOCKED / FLAG
|
||
- [ ] No sibling PLAN/CONCEPT twins for the same subject (CONVENTIONS)
|
||
|
||
## Research-backed requirements
|
||
|
||
Musts already encoded in CONCEPT (morning 2026-10-01 commits). Do not weaken in review copy.
|
||
|
||
- **Ticket shape (must):** field + wrong value + right value + proof URL (GBP / claimed truth). Same shape for Lane A and Lane B.
|
||
- **Two lanes (must):** Lane A umbrellas (Data Axle, Localeze, Foursquare) stop feed regen; Lane B claim / suggest-edit on own-DB surfaces. Umbrella-only or platform-only both fail.
|
||
- **One-click = ticket set (must):** not one syndication rewrite of the internet. Mint GBP-proof + Lane A + Lane B; re-audit = success check.
|
||
- **Fan-out ceiling (must productize honesty):** Localeze claim-once → many publishers, partner cadence often ~30–90 days, no partner-acceptance guarantee; Google fast-path needs separate verify/sync inside their product; Data Axle hours to ~two weeks on hard cases; **no free public one-to-many SMB fan-out API**; Yext-class = paid pipe not destination; GBP does **not** outbound-syndicate NAP; Apple writes Apple ecosystem only.
|
||
- **Held verification:** multi-platform verified status = moat; paid / fulfillment architecture, not free first-hour (align with BUSINESS_PLAN paid cleanup = fulfillment, not the product center).
|
||
- **Presence score inputs (open):** Core 3 min-bar lives in BUSINESS_PLAN + genre-packs. CONCEPT still open on Yelp + aggregators in v1 Presence. **FLAG** before claiming “we check X.”
|
||
- **V1 shell FLAG:** CONCEPT = interactive web first, revisit MCP ~3 months; BUSINESS_PLAN Owner MCP P0 parallel with web chat. Packaging must not pick a side. **FLAG for Ty.**
|
||
|
||
## Decisions locked (do not re-litigate in review)
|
||
|
||
1. Agent-era local SMB discoverability is the spine; MCP is implementation option, not the strategy product.
|
||
2. Industry graph is longer-term Northstar, not v1.
|
||
3. Single SoT file for self-serve AI discoverability = CONCEPT (amend in place).
|
||
4. Presence + Recommendability as the two scored outcomes of the North Star intent.
|
||
5. Two-lane remediation: umbrellas (A) + per-platform (B); ranked majors with owner remediation paths.
|
||
6. Stakeholder verification before honest audit / warehouse overwrite is core pain and action-plan step A.
|
||
7. Collaborator/chat-first process: write only on explicit amend/capture; no doc mill.
|
||
|
||
## Remediations: resolve vs flag taxonomy
|
||
|
||
| Class | Meaning | Reviewer action |
|
||
| :--- | :--- | :--- |
|
||
| **Resolve** | Owner (or product) can complete a concrete correction path with a known surface. Acceptance can be tracked. | Expect ticket shape: wrong value → right value → proof link → platform channel. |
|
||
| **Flag** | Known gap, commercial unknown, or timing risk that blocks shipping a path. | Keep visible; do not invent a product decision to close it. |
|
||
| **Hybrid (demoted)** | Earlier hybrid genre/parent framing — demoted to a flag unless CONCEPT re-elevates it. | Do not treat as locked architecture. |
|
||
|
||
Lane A: Data Axle, Localeze/TransUnion, Foursquare. Lane B: GBP first as proof, then other ranked platforms (see CONCEPT 1–14).
|
||
|
||
### Ranked stack 1–14 (status for review)
|
||
|
||
Documented with owner workflows in CONCEPT (commits `20b1f9f` → `95cd0a1` → `967ba9a`). All are **architect-not-built** Resolve paths unless noted Flag.
|
||
|
||
| Rank | Surface | Lane | Status |
|
||
| :---: | :--- | :--- | :--- |
|
||
| 1 | Google Business Profile | B (claim hub / Core 3) | Resolve path documented |
|
||
| 2 | Apple Business Connect | B (Core 3) | Resolve path documented |
|
||
| 3 | Bing Places | B (Core 3) | Resolve path documented |
|
||
| 4 | Foursquare Places | A + B | Resolve path documented |
|
||
| 5 | Yelp | B | Resolve path documented |
|
||
| 6 | Data Axle Local Listings | A | Resolve path documented |
|
||
| 7 | Localeze / TransUnion | A | Resolve path documented |
|
||
| 8 | YP / Thryv | B (long-tail feeds) | Resolve path documented |
|
||
| 9 | Tripadvisor | B (vertical) | Resolve path documented; **FLAG** thin for bakery/salon v1 genre gate |
|
||
| 10 | Facebook / Meta | B (low weight) | Resolve path documented |
|
||
| 11 | MapQuest / HERE / in-car / long-tail | A by default | Monitor after umbrellas; **FLAG** thin for v1 genre gate |
|
||
| 12 | Dun & Bradstreet | Low for consumer local | Skip unless B2B; **FLAG** thin for v1 |
|
||
| 13 | CityGrid | Legacy | Only if still stomping; **FLAG** thin for v1 |
|
||
| 14 | Yext / Uberall / BrightLocal (pipes) | Route through existing paid pipe | Not destinations; score publishers not pipe brand |
|
||
|
||
## Platform links / fan-out — confirm / flag
|
||
|
||
Desk pass against CONCEPT hyperlinks and fan-out section (commit `967ba9a` / `44c2d6c`). No external re-research in this package.
|
||
|
||
| Item | Verdict | Notes |
|
||
| :--- | :--- | :--- |
|
||
| Ranks 1–14 marketing-root hyperlinks in CONCEPT | **CONFIRM** | Canonical pages linked in SoT (`967ba9a`) |
|
||
| Deep correction URLs / API per rank 1–14 | **FLAG** | SOURCES covers Core 3 field/API only; need second table for deep edit channels |
|
||
| Localeze “80–100+” vs ALTERNATE “80–90+” | **SOFT FLAG** | Align publisher-count language across CONCEPT and ALTERNATE |
|
||
| Localeze ~30–90d partner cadence + Google sync separate | **CONFIRM** | Encoded in CONCEPT fan-out section |
|
||
| Data Axle timing / free vs Premium docs link | **CONFIRM** | Hours–~2 weeks hard cases; Premium docs linked |
|
||
| Yext-class “often 200+” direct publisher APIs | **FLAG** | Cite evidence or soften number before locking |
|
||
| Foursquare suggest/edit (`POST /places/{id}/suggest/edit`) | **CONFIRM** | In CONCEPT workflows |
|
||
| No free public one-to-many fan-out API | **CONFIRM** | Product rule: one-click = ticket set |
|
||
| GBP no outbound NAP syndicate; Apple ≠ rivals | **CONFIRM** | Architect rule in CONCEPT |
|
||
|
||
### Platform link inventory (marketing roots in CONCEPT)
|
||
|
||
| # | Label | URL in CONCEPT |
|
||
| :---: | :--- | :--- |
|
||
| 1 | Google Business Profile | https://business.google.com |
|
||
| 2 | Apple Business Connect | https://business.apple.com |
|
||
| 3 | Bing Places | https://www.bingplaces.com |
|
||
| 4 | Foursquare | https://foursquare.com |
|
||
| 5 | Yelp | https://www.yelp.com |
|
||
| 6 | Data Axle Local Listings | https://www.data-axle.com/marketing-solutions/local-listings-management/ |
|
||
| 6b | Local Listings Premium docs | https://local-listings-premium.data-axle.com/docs |
|
||
| 7 | Localeze / TransUnion | https://neustarlocaleze.biz/ |
|
||
| 8 | YP / Thryv | https://www.yellowpages.com |
|
||
| 9 | Tripadvisor | https://www.tripadvisor.com |
|
||
| 10 | Facebook / Meta Business | https://www.facebook.com/business |
|
||
| 11 | MapQuest | https://www.mapquest.com |
|
||
| 12 | Dun & Bradstreet | https://www.dnb.com |
|
||
| 13 | CityGrid | https://www.citygrid.com |
|
||
| 14 | Yext | https://www.yext.com |
|
||
| 14b | Uberall | https://www.uberall.com |
|
||
| 14c | BrightLocal | https://www.brightlocal.com |
|
||
|
||
## Weak / contradictory — flag before Ty reviews
|
||
|
||
1. **MCP vs web-first:** BUSINESS_PLAN §8 (Owner MCP P0 parallel) vs CONCEPT (interactive web first, MCP ~3 months). Do not pick a side in packaging. **FLAG for Ty.**
|
||
2. **Rank vs regeneration:** FSQ/Yelp sit above Data Axle/Localeze in discoverability rank; that is not the same as regeneration-stop priority. Keep both frames labeled. **FLAG** if copy conflates them.
|
||
3. **Thin verticals in 1–14:** Tripadvisor / MapQuest / D&B / CityGrid are thin for bakery/salon v1. Gate the 14-stack by genre for v1 packs. **FLAG.**
|
||
4. **Held verification moat:** Do not sell as free checkup. How (OAuth / agency / ToS) is unproven. **FLAG.**
|
||
5. **Marketing roots ≠ deep edit links:** Need a second table; SOURCES pattern is Core 3 only today. **FLAG.**
|
||
6. **Localeze publisher count:** Align CONCEPT 80–100+ with ALTERNATE 80–90+. **SOFT FLAG.**
|
||
7. **Yext 200+:** Cite or soften. **FLAG.**
|
||
|
||
## Open decisions already listed in CONCEPT (do not invent closures)
|
||
|
||
- First genre cluster pack(s) to ship
|
||
- Web-only v1 vs also embed in a chat shell (see MCP FLAG above)
|
||
- Presence providers for v1 (Core 3 ± Yelp ± aggregators)
|
||
- How to measure Recommendability without overclaiming
|
||
- Where “email on file” for verify comes from
|
||
- Free vs paid; what never goes to a human vs escalation
|
||
- Veterinary: healthcare/regulated vs own call (GBP Pets ~59 leaves)
|
||
- v1 demand: ads/self-start only, intermediate-first, or both
|
||
|
||
## Top review checklist
|
||
|
||
1. Open CONCEPT first — baker/owner story include prove-you-own-it + black-box copies?
|
||
2. Solution still “to architect,” not claimed shipped?
|
||
3. Tickets: every audit finding → same ticket shape; GBP as proof?
|
||
4. Moat: held multi-platform verified status?
|
||
5. Genre parents match latest CONCEPT (destination workshop split, beauty ≠ healthcare, hybrid = flag)?
|
||
6. ALTERNATE clearly non-SoT; action plan coherent with CONCEPT lanes?
|
||
7. BUSINESS_PLAN §1 intent verbatim where North Star quoted?
|
||
8. Evidence under `docs/evidence/` only for cited research?
|
||
9. PDF vs ALTERNATE research section — match or note drift?
|
||
10. No new sibling docs without announced path (CONVENTIONS)?
|
||
11. Fan-out honesty visible (ticket set, not one rewrite)?
|
||
12. MCP vs web-first contradiction left as FLAG (not silently resolved)?
|
||
|
||
## Branch map
|
||
|
||
| Branch | Tip (at package prep) | Role for this review |
|
||
| :--- | :--- | :--- |
|
||
| **`planning-selfserve-audit`** | `8337408` (+ this REVIEW commit) | **YES — review surface.** Self-serve concept SoT, remediation 1–14, fan-out, alternate proposal, writing rules. |
|
||
| `planning-rev2` | `9efd554` | Background. Sep 15 SEO desk unslop; BUSINESS_PLAN / genre-packs / evidence lineage. Parent of hot branch. |
|
||
| `main` | `2aa7a2c` | Historical. July strategy / SSP archive. Raw material only; not current SoT on this review. |
|
||
| `ssp-refinement` | `a4cc4cd` | Historical. Conversational SSP UC-04/05 (July). Behind `main`; not current SoT. |
|
||
| `review/ready` | (optional integrator scratch) | Earlier mechanical prep fork; prefer **this** branch (`planning-selfserve-audit`) as Ty review surface. |
|
||
|
||
Do not mass-delete remote branches. Prefer documenting over force-rewriting history.
|
||
|
||
## Out of scope for this review package
|
||
|
||
Coding, production deploy, force-push `main`, SlabUploader work, expanding ALTERNATE/PDF without Ty naming paths, inventing Presence “we check X” lists, closing MCP vs web-first without Ty.
|
||
|
||
## Research flags (Desk)
|
||
|
||
Desk confirm/flag table is above. Remaining open research items for Ty (not closed here): deep edit URL table; Localeze count align; Yext 200+ cite-or-soften; genre-gated 14-stack for v1 packs.
|