12 KiB
Path to Proof-of-Concept — General-Purpose Layered Sequence
Master path: docs/architecture/path-to-poc-sequencing.md
Client-specific artifacts: docs/clients/<client-name>/
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.
All layers enforce:
- Evidence Model (Tier 1 Verified / Tier 2 Indicative)
- Draft → human approve → lock gates
- No invented client numbers
- Strict ordering: Users → Problems → Requirements → Workflows → Agents → Tools
Layer 1: Account Intelligence
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.
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
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
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.
Primary Artifact: docs/clients/<client-name>/data-inventory-v1.md and data/clients/<client-name>/raw/
Layer 2: Threat Diagnosis
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
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
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.
Primary Artifact: docs/clients/<client-name>/threat-register-v1.md
Layer 3: Economics & Pricing Validation
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."
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
- At least three pricing bands documented:
- Band A: What the client would pay for detection-only (agent drafts, human reviews)
- Band B: What the client would pay for detection + draft response (agent drafts the reply, human approves)
- Band C: What the client would pay for full escalation (agent detects, drafts, and alerts with next-action recommendation)
- Each band is tagged: Tier 1 (owner confirmed) or Tier 2 (owner indicated but not committed)
- 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:
- 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.
Primary Artifacts: docs/architecture/pricing-bands-v1.md (cross-client model) / docs/clients/<client-name>/economics-v1.md (client-specific numbers)
Layer 4: Response Requirements
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).
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")
- Requirements that would exceed the client's stated pricing band are explicitly marked out of scope for V1 with the pricing band ceiling noted
- 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.
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/<client-name>/requirements-v1.md
Layer 5: Workflow Engineering
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
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)
- Data dependencies (what source it reads, what artifact it writes)
- Failure path (what happens if data is stale or signal is ambiguous)
- Cadence (continuous / daily / weekly / event-triggered)
- Pricing band tier (A / B / C) — must match what the client agreed to pay
- Every workflow incorporates the draft → human review → lock gate explicitly
- 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.
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/<client-name>/workflows-v1.md
Layer 6: Agent Build & Test
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
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.
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/<client-name>/build-log-v1.md. Agents live under agents/<client-name>/. Tool configs stay in environment (not committed secrets).
Layer 7: POC Delivery & Retainer Conversation
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.
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.
- A clear gap document exists: what is not yet covered, what data is still missing, and estimated effort to close
- 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.
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/<client-name>/poc-demo-notes-v1.md, docs/clients/<client-name>/gap-analysis-v1.md, docs/architecture/v1-delivery-architecture.md
Readiness Notes
- General-purpose across local service verticals
- 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)
- No invented client numbers
- Every blocker is surfaced
- Agents appear only at Layer 6
- Master sequencing document lives at this path