From 02b2be80f6237817c38d093ed78cfc6d77e2aa8b Mon Sep 17 00:00:00 2001 From: Ty Date: Mon, 3 Aug 2026 05:13:01 +0000 Subject: [PATCH] Split Layer 1 into 1a Public and 1b Owner-access; align cold audit vs paid engagement --- docs/architecture/path-to-poc-sequencing.md | 118 +++++++++++++------- 1 file changed, 75 insertions(+), 43 deletions(-) diff --git a/docs/architecture/path-to-poc-sequencing.md b/docs/architecture/path-to-poc-sequencing.md index e48c4f0..dc84b40 100644 --- a/docs/architecture/path-to-poc-sequencing.md +++ b/docs/architecture/path-to-poc-sequencing.md @@ -3,7 +3,7 @@ **Master path:** `docs/architecture/path-to-poc-sequencing.md` **Client-specific artifacts:** `docs/clients//` -This sequence is reusable across local service verticals (salon, home services, auto repair, fitness, etc.). The first real client (Phoenix Salon + Spa or equivalent) serves as the validation anchor for economics and proof, but the layers themselves remain general. +This sequence is reusable across local service verticals (salon, home services, auto repair, fitness, etc.). The first client that completes Layers 1–3 with real data serves as the validation anchor for economics and proof. Layers themselves remain general. All layers enforce: - Evidence Model (Tier 1 Verified / Tier 2 Indicative) @@ -13,24 +13,54 @@ All layers enforce: --- -## Layer 1: Account Intelligence +## Layer 1: Account Intelligence (split: 1a Public / 1b Owner-access) **Purpose:** Establish ground truth of the client's digital presence — what data exists, where it lives, and what shape it's in. No analysis, no diagnosis, just ingestion and baseline. -**Entry Criteria:** Nothing. This is the first layer. +Layer 1 is **two sequential sub-layers** so cold prospecting is not permanently blocked by owner-access requirements. -**Exit Criteria:** -- Client GMB, website, primary social channel, and booking/system data ingested into structured storage -- Each data source tagged at Tier 1 (verified) or Tier 2 (indicative) per the Evidence Model -- Data quality issues (missing months, gaps, unreachable sources) documented as blockers -- A client data inventory exists listing what we have, what we're missing, and verification status per source -- Human review has confirmed the inventory is accurate before Layer 2 begins +### Layer 1a — Public baseline (cold audit / prospecting) -**Required Data:** Client GMB profile (owner access), primary social channel (owner access), website URL, booking or CRM system credentials if available, at least 6 months of history +**Entry criteria:** Nothing. This is the first sub-layer. -**Blocked If Missing:** If GMB or the primary social channel is inaccessible, the data inventory will have gaping holes. Layer 1 cannot close. Resolve access before proceeding. +**Exit criteria:** +- Public sources ingested into a Data Inventory: website, public GBP snapshot (via form or equivalent), primary social links visible from the site or public profiles, observable review/directory surfaces, booking CTA state as visible without login +- Every source tagged **Tier 2** (or Tier 1 only if independently instrument-verified without owner login) +- Snapshot Date recorded for every source +- Gaps and unreachable sources documented as blockers +- Human review confirms the inventory accurately reflects **what was publicly observable** +- Status may be **Locked (1a)** or held as **Draft Benchmark** for training; either is a valid exit of 1a -**Primary Artifact:** `docs/clients//data-inventory-v1.md` and `data/clients//raw/` +**Required data:** Public URLs and human GBP snapshot fields. **Owner access is not required.** + +**Blocked if missing:** If even public website and a GBP snapshot attempt are impossible, 1a cannot close. Document the blocker. + +**What 1a does *not* claim:** Full Layer 1 complete for paid engagement. Tier ceiling is typically Tier 2. Layer 2 may proceed on 1a **only** with all threats Tier 2 and explicitly provisional; economics (Layer 3) still requires a real engagement path. + +**Primary artifact:** `docs/clients//data-inventory-v1.md` (status notes 1a vs 1b) + +--- + +### Layer 1b — Owner-access baseline (paid / engaged) + +**Entry criteria:** Layer 1a inventory exists and is human-reviewed (Locked 1a or accepted Draft with explicit blockers). + +**Exit criteria:** +- Owner access obtained where available: GBP (owner), primary social (owner), booking/CRM credentials if used +- At least partial history where the system provides it; gaps still documented +- Sources upgraded to Tier 1 where verification now supports it +- Data quality issues (missing months, denied access) documented as blockers +- Human review confirms inventory accuracy **including owner-gated fields** before treating Layer 1 as fully complete for Layers 3+ + +**Required data:** Owner GBP and/or social access preferred; booking/CRM if the client uses them. Six months of history is a **target**, not a hard block — missing history is a documented gap, not invented zeros. + +**Blocked if missing:** If owner declines all access, 1b does not close. Remain on 1a + Tier 2 path; do not invent Tier 1. + +**Primary artifact:** Same inventory file, updated; optional raw under `data/clients//raw/` + +**Terminology:** +- **Layer 1 complete (engagement-ready)** = 1a + 1b human-confirmed, or 1a only with explicit “1b declined / blocked” and Tier 2 ceiling accepted for downstream risk. +- Cold audits stop cleanly at **1a Locked** or Draft Benchmark without lying that full Layer 1 closed. --- @@ -38,19 +68,20 @@ All layers enforce: **Purpose:** Identify specific customer-acquisition and retention failures in the client's current digital presence. Each threat must be grounded in data from Layer 1, not speculation. -**Entry Criteria:** Layer 1 data inventory is complete and human-confirmed +**Entry criteria:** Layer 1a data inventory is complete and human-confirmed (1b preferred for engagement work). -**Exit Criteria:** -- A ranked threat register with every entry tagged: Tier 1 (verified) or Tier 2 (indicative) +**Exit criteria:** +- A ranked threat register with every entry tagged: Tier 1 (Verified) or Tier 2 (Indicative) - Each threat includes: signal source, evidence snippet, estimated severity (critical / major / minor), and data recency date - The signal-draft is produced by the agent; a human has reviewed and either verified or downgraded each entry before the register is locked - Only threats with real client data backing them appear in the register — no invented gaps +- Competitor facts, if present, follow competitor evidence rules in the Audit Playbook (never primary claim; Tier 2 default; snapshot + source required) -**Required Data:** All data from Layer 1. No new sources required, but may need deeper history on specific sources if signals are ambiguous. +**Required data:** All data from Layer 1. No new sources required, but may need deeper history on specific sources if signals are ambiguous. -**Blocked If Missing:** Every gap in Layer 1 data propagates here as an unknown. A missing GMB review history means "unknown threat status on review response" — documented as blind spot, not as zero threat. +**Blocked if missing:** Every gap in Layer 1 data propagates here as an unknown. A missing GBP review history means "unknown threat status on review response" — documented as blind spot, not as zero threat. -**Primary Artifact:** `docs/clients//threat-register-v1.md` +**Primary artifact:** `docs/clients//threat-register-v1.md` --- @@ -58,9 +89,9 @@ All layers enforce: **Purpose:** Force real client financial numbers into the economic model and pricing bands. This layer cannot be skipped — it converts threat severity into financial impact and establishes what this client is willing to pay to close each gap. -**Entry Criteria:** Threat register from Layer 2 is locked. At least one verified (Tier 1) or indicative (Tier 2) threat must exist to anchor pricing. If zero threats survived Layer 2, this layer produces a single output: "No validated acquisition gaps — revisit data baseline before pricing." +**Entry criteria:** Threat register from Layer 2 is locked. At least one verified (Tier 1) or indicative (Tier 2) threat must exist to anchor pricing. If zero threats survived Layer 2, this layer produces a single output: "No validated acquisition gaps — revisit data baseline before pricing." -**Exit Criteria:** +**Exit criteria:** - Current client revenue baseline documented (monthly / quarterly top line from owner-provided numbers — no invented figures) - Owner-estimated cost of each verified threat in lost revenue or wasted spend (owner-provided estimates, not speculative projections) - Owner-stated willingness to pay (WTP) per monitored channel or per detected signal — captured as a range, not a single number @@ -72,15 +103,15 @@ All layers enforce: - Human (client owner) has reviewed the pricing bands and confirmed they are in the right ballpark before Layer 4 begins - If the owner declines to share revenue numbers, the pricing model is documented as Tier 2 only and flagged as a risk to any retainer conversation -**Required Data:** +**Required data:** - Current monthly revenue (owner-provided; not scraped) - Current monthly ad spend across all channels (owner-provided) - Owner's own estimate of "what a problem like this costs me per month" - Owner's gut check on willingness to pay (casual conversation — does not require a signed contract) -**Blocked If Missing:** Without revenue baseline or WTP conversation, the economics layer produces placeholder bands only. The pricing model cannot be validated, and any retainer discussion at Layer 7 will be speculative. This layer cannot close without a human conversation with the client owner. +**Blocked if missing:** Without revenue baseline or WTP conversation, the economics layer produces placeholder bands only. The pricing model cannot be validated, and any retainer discussion at Layer 7 will be speculative. This layer cannot close without a human conversation with the client owner. -**Primary Artifacts:** `docs/architecture/pricing-bands-v1.md` (cross-client model) / `docs/clients//economics-v1.md` (client-specific numbers) +**Primary artifacts:** `docs/architecture/pricing-bands-v1.md` (cross-client model) / `docs/clients//economics-v1.md` (client-specific numbers) --- @@ -88,9 +119,9 @@ All layers enforce: **Purpose:** Derive what the system must be capable of doing, based on the verified threats and the economic reality of what the client will pay. Not yet workflow design — functional requirements anchored to evidence and budget. -**Entry Criteria:** Threat register from Layer 2 is locked and human-approved. Economics from Layer 3 is locked (or documented as speculative if owner declined to share numbers). +**Entry criteria:** Threat register from Layer 2 is locked and human-approved. Economics from Layer 3 is locked (or documented as speculative if owner declined to share numbers). -**Exit Criteria:** +**Exit criteria:** - One functional requirement per verified critical/major threat, scoped to the pricing band the client has indicated - Each requirement is traceable back to its threat ID in the register - Requirements are expressed as outcomes ("Loss of bookings from unanswered GMB Q&A must be detected within 24 hours"), not as system features ("build a Q&A monitor") @@ -98,11 +129,11 @@ All layers enforce: - Human review has confirmed that no requirement is broader than what the evidence and the budget support - Requirements that cannot be closed without data the client does not have are explicitly marked as speculative -**Required Data:** Threat register from Layer 2. Pricing bands from Layer 3. No new raw data. +**Required data:** Threat register from Layer 2. Pricing bands from Layer 3. No new raw data. -**Blocked If Missing:** If Layer 2 exit hung on missing data (zero verified threats), or Layer 3 produced only speculative pricing, Layer 4 should produce a single requirement: "Establish data baseline and pricing agreement before further diagnosis." +**Blocked if missing:** If Layer 2 exit hung on missing data (zero verified threats), or Layer 3 produced only speculative pricing, Layer 4 should produce a single requirement: "Establish data baseline and pricing agreement before further diagnosis." -**Primary Artifact:** `docs/clients//requirements-v1.md` +**Primary artifact:** `docs/clients//requirements-v1.md` --- @@ -110,9 +141,9 @@ All layers enforce: **Purpose:** Define the operational sequences that fulfill each requirement. Still no agents/tools — just the human-and-system steps, decision points, frequency, and data flows. Each workflow must stay within the pricing band the client approved. -**Entry Criteria:** Requirements from Layer 4 are locked and human-approved +**Entry criteria:** Requirements from Layer 4 are locked and human-approved -**Exit Criteria:** +**Exit criteria:** - One documented workflow per non-speculative requirement, each with: - Trigger condition (what starts it) - Step sequence (agent drafts, human reviews, human approves or rejects, action follows) @@ -124,11 +155,11 @@ All layers enforce: - Human has walked through each workflow and confirmed it matches the client's operational reality (business hours, staffing, seasonal variation) - Speculative-flagged requirements have documented "wait for data" workflows only (no action) -**Required Data:** For each threat's workflow, may need to validate the trigger frequency against real business hours, staffing patterns, or seasonal variation. +**Required data:** For each threat's workflow, may need to validate the trigger frequency against real business hours, staffing patterns, or seasonal variation. -**Blocked If Missing:** A workflow assuming "daily review" is wrong for a business that operates Tuesday–Saturday. Workflow cadences are preliminary until confirmed by the owner. +**Blocked if missing:** A workflow assuming "daily review" is wrong for a business that operates Tuesday–Saturday. Workflow cadences are preliminary until confirmed by the owner. -**Primary Artifact:** `docs/clients//workflows-v1.md` +**Primary artifact:** `docs/clients//workflows-v1.md` --- @@ -136,20 +167,20 @@ All layers enforce: **Purpose:** Implement the first agent(s) capable of executing the workflows using real client data. This is the build layer. -**Entry Criteria:** Workflows from Layer 5 are locked and human-approved +**Entry criteria:** Workflows from Layer 5 are locked and human-approved -**Exit Criteria:** +**Exit criteria:** - One functional agent per workflow, executing against real (not synthetic) client data - Agent outputs are always drafts — no automated publish path exists - Each agent has passed the signal-detection test: given a known signal from Layer 2's register, it produces the correct draft alert - All tool configurations (API keys, data source connections, cron schedules) are documented in a build log - Human has reviewed at least one full agent run and confirmed the output is correct before signing off -**Required Data:** Live access to client GMB, social channel, booking system during testing. Stale test data will pass tests but fail in production. +**Required data:** Live access to client GBP, social channel, booking system during testing. Stale test data will pass tests but fail in production. -**Blocked If Missing:** Cannot run integration tests without live connections. If the client has restricted access at this stage, test against the Layer 1 snapshots (Tier 2 quality only) and mark the agent as pending live verification. +**Blocked if missing:** Cannot run integration tests without live connections. If the client has restricted access at this stage, test against the Layer 1 snapshots (Tier 2 quality only) and mark the agent as pending live verification. -**Primary Artifacts:** `docs/clients//build-log-v1.md`. Agents live under `agents//`. Tool configs stay in environment (not committed secrets). +**Primary artifacts:** `docs/clients//build-log-v1.md`. Agents live under `agents//`. Tool configs stay in environment (not committed secrets). --- @@ -157,9 +188,9 @@ All layers enforce: **Purpose:** Show the client a working, real-data proof-of-concept that demonstrates detectable threats and the draft-review-publish loop, framed against the pricing bands they validated in Layer 3. This is the conversation, not the close. -**Entry Criteria:** Layer 6 agents are functional and human-tested. Economics from Layer 3 is available for the retainer framing. +**Entry criteria:** Layer 6 agents are functional and human-tested. Economics from Layer 3 is available for the retainer framing. -**Exit Criteria:** +**Exit criteria:** - Client owner has seen a live agent alert (draft form) and understands the review-then-approve flow - At least one critical-path threat has been successfully detected, drafted as an alert, reviewed, and the owner has confirmed the signal is real - A minimal V1 delivery architecture is defined and captured — what runs where, what data sources feed it, how the human review loop works, and how alerts reach the owner. This is a one-page architecture sketch, not a full spec. @@ -167,11 +198,11 @@ All layers enforce: - Client owner has verbally (or in writing) indicated retention interest - Pricing bands from Layer 3 are attached to the retainer discussion as the proposed commercial model -**Required Data:** Live running agents on client data. No new sources. +**Required data:** Live running agents on client data. No new sources. -**Blocked If Missing:** If no verified critical threat survived Layers 2–4, the demo may be underwhelming. In that case, POC should demonstrate the system itself (how it would detect if data existed) and flag this as a data-quality finding, not a product failure. If Layer 3 pricing is entirely Tier 2 (speculative), the retainer conversation is provisional and must be framed as such. +**Blocked if missing:** If no verified critical threat survived Layers 2–4, the demo may be underwhelming. In that case, POC should demonstrate the system itself (how it would detect if data existed) and flag this as a data-quality finding, not a product failure. If Layer 3 pricing is entirely Tier 2 (speculative), the retainer conversation is provisional and must be framed as such. -**Primary Artifacts:** `docs/clients//poc-demo-notes-v1.md`, `docs/clients//gap-analysis-v1.md`, `docs/architecture/v1-delivery-architecture.md` +**Primary artifacts:** `docs/clients//poc-demo-notes-v1.md`, `docs/clients//gap-analysis-v1.md`, `docs/architecture/v1-delivery-architecture.md` --- @@ -181,6 +212,7 @@ All layers enforce: - Charter-compliant (Evidence Model + draft → approve gates at every layer) - Follows Users → Problems → Requirements → Workflows → Agents → Tools - Economics & Pricing Validation is non-skippable (Layer 3) +- Layer 1a enables cold audits; Layer 1b enables engagement-grade Tier 1 - No invented client numbers - Every blocker is surfaced - Agents appear only at Layer 6