12 KiB
12 KiB
Review package - planning-selfserve-audit
Repo: Ty_Tech/geolocal-io
Review branch: planning-selfserve-audit
Package commit: tip after this file lands (see git log on planning-selfserve-audit)
Primary SoT: docs/SELF_SERVE_AI_DISCOVERABILITY_CONCEPT.md
Strategy spine: docs/BUSINESS_PLAN.md §1 North Star
Conventions: docs/CONVENTIONS.md · docs/writing-rules.md
Parallel (non-SoT): docs/ALTERNATE_BUSINESS_PROPOSAL.md · docs/research-brief.pdf
Field / API evidence (Core 3): 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 FLAGged 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)
- Agent-era local SMB discoverability is the spine; MCP is implementation option, not the strategy product.
- Industry graph is longer-term Northstar, not v1.
- Single SoT file for self-serve AI discoverability = CONCEPT (amend in place).
- Presence + Recommendability as the two scored outcomes of the North Star intent.
- Two-lane remediation: umbrellas (A) + per-platform (B); ranked majors with owner remediation paths.
- Stakeholder verification before honest audit / warehouse overwrite is core pain and action-plan step A.
- 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
- 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.
- 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.
- 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.
- Held verification moat: Do not sell as free checkup. How (OAuth / agency / ToS) is unproven. FLAG.
- Marketing roots ≠ deep edit links: Need a second table; SOURCES pattern is Core 3 only today. FLAG.
- Localeze publisher count: Align CONCEPT 80-100+ with ALTERNATE 80-90+. SOFT FLAG.
- 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
- Open CONCEPT first - baker/owner story include prove-you-own-it + black-box copies?
- Solution still “to architect,” not claimed shipped?
- Tickets: every audit finding → same ticket shape; GBP as proof?
- Moat: held multi-platform verified status?
- Genre parents match latest CONCEPT (destination workshop split, beauty ≠ healthcare, hybrid = flag)?
- ALTERNATE clearly non-SoT; action plan coherent with CONCEPT lanes?
- BUSINESS_PLAN §1 intent verbatim where North Star quoted?
- Evidence under
docs/evidence/only for cited research? - PDF vs ALTERNATE research section - match or note drift?
- No new sibling docs without announced path (CONVENTIONS)?
- Fan-out honesty visible (ticket set, not one rewrite)?
- 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.