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

Add REVIEW.md review package; sync branch labels

Browse Source 
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.
This commit is contained in:
grokbot_ty
2026-10-01 13:26:44 -07:00
parent 8337408f5b
commit 5ac84b6ca5
3 changed files with 199 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
REVIEW.md
+183
View File
@@ -0,0 +1,183 @@
# 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.