From 7386a0614a6067ac736b8932e8a55f22ba2c510c Mon Sep 17 00:00:00 2001 From: Leonard Date: Sat, 25 Jul 2026 14:39:23 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20add=20GLOSSARY.md=20=E2=80=94=20canonic?= =?UTF-8?q?al=20core=20terminology=20for=20Digital=20Operations=20Partner?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/GLOSSARY.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/GLOSSARY.md diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md new file mode 100644 index 0000000..25af6ea --- /dev/null +++ b/docs/GLOSSARY.md @@ -0,0 +1,149 @@ +# GLOSSARY.md + +**Status**: Canonical + +This is the single source of truth for all core terminology. Other documents must link here instead of redefining terms. Changes require an ADR citing motivating evidence. + +--- + +## Core Mission Terms + +### Silent Customer Loss +Umbrella term for customer acquisition problems that occur without the business owner clearly seeing or measuring the loss. It comprises two primary modes (a Finding is classified by its *primary* mode; when both apply, Customer Path Leakage takes precedence if a concrete pathway friction exists): + +- Customer Path Leakage — interest/intent exists, but friction prevents contact, booking, or visit. +- Discovery Failure — the customer, search engine, or AI system never finds or accurately represents the business. + +### Customer Path Leakage +A potential customer has interest or intent but fails to contact, book, visit, or engage because of digital friction (wrong phone, broken booking link, incorrect hours, failed form, confusing service information, inaccurate listing data, etc.). + +### Discovery Failure +A potential customer never meaningfully encounters the business because customers, search engines, or AI systems do not find, understand, surface, or accurately represent it (weak local visibility, incomplete entity signals, missing service clarity, absence from AI samples, poor structured data, inconsistent citations, etc.). + +### Customer Path Integrity +Operational domain responsible for ensuring that once a customer is interested, the digital pathway to contact/booking/visit is free of friction. + +Owned surfaces: Google Business Profile (core fields, hours, phone, booking link, services), website contact paths and booking systems, primary citations for NAP consistency. + +### AI Visibility Integrity (AEO) +Operational domain responsible for ensuring AI-assisted discovery systems can accurately understand and represent the business. + +Owned surfaces: Structured data / schema, FAQ content, entity clarity signals, sampled AI answer testing, GBP consistency as it affects AI understanding. + +No promises of placement, recommendation, or citation by any AI system. + +### Local Competitive Awareness +Supporting capability (not a standalone product) that monitors relevant competitors for changes affecting the client's visibility or customer path. Depth scales with service tier. Built-in for every client at a baseline level; deeper continuous monitoring is tiered. + +### Mission Scope vs Contract Scope +- Mission Scope: Any digital issue that can affect customer acquisition, visibility, trust, or conversion may be identified. +- Contract Scope (Version 1): Monitoring, diagnosis, prioritization, reporting, and approved low-risk optimizations only. Social media production, paid ads, website redesign, branding, full SEO campaigns, and CRM/email are excluded. + +### Version 1 +The initial commercial offering defined by the current Contract Scope, evidence model, Approval Gate, and the check catalog in specifications/checks/checks.yaml. + +--- + +## Evidence Model + +### Verified Evidence (Tier 1) +A finding that meets all of the following: +- Reproducible and deterministic method (sampling or probabilistic methods are excluded) +- Captured artifact (raw payload or screenshot) +- SHA-256 hash of the artifact +- UTC timestamp of capture +- Current within the defined freshness window (measured from capture time to the moment of client-facing use; default 7 days unless the check specifies otherwise) + +May be presented to clients as a confirmed issue. + +### Indicative Evidence (Tier 2) +Sampled, directional, or probabilistic findings that suggest risk or opportunity but do not prove direct customer loss. Must always be labeled as directional. Cannot be upgraded to Verified without additional concrete evidence meeting the full Verified criteria (including deterministic method). + +### Evidence Tier Assignment Authority +Agents may propose a tier. Final tier used in any client-facing report requires human approval in Version 1. Ambiguous findings default to Indicative. A rejected Tier 1 proposal defaults to Tier 2 unless the finding is discarded or more evidence is requested. + +### Finding +A single structured result produced by a Check against a Client during a Run. Contains check_id, domain, status, proposed_tier, approved_tier, evidence references, and remediation state. + +### Run +A complete execution of the check catalog (or a defined subset) against one Client at a point in time. Produces a set of Findings and an immutable evidence store. + +### Client +A local service business enrolled in the service. Represented by a structured profile containing authorized surfaces, contact details, and scope of engagement. + +### Agent +Any automated or semi-automated system (including language models) that detects, drafts, or proposes actions. A human operating through an Agent remains fully bound by the Approval Gate; the Agent does not create an exception. + +--- + +## Operating Rules + +### Approval Gate (Reconnaissance vs Execution) +Agents may detect, gather evidence, and draft. +Any change that publishes to a client-facing surface requires explicit human approval before going live. + +### Client-Facing Surface +A surface that the client's customers or the public can see or interact with (GBP fields, review responses, Q&A, business descriptions, hours, phone numbers, booking links, website content, directory listings, citations). + +An external_ai response surface is not client-facing. + +### Owner Surface +The platform or system a Check targets (e.g., gbp, website). + +### Low-Risk Fix +A remediation that meets all of the following: +- Changes a single field or discrete, isolated attribute (e.g., a URL value, phone number, email address, or hours entry) +- Has a documented and tested rollback +- Contains no legal, medical, pricing, or compliance claims +- Does not alter website structure, navigation, or marketing copy (single-attribute website changes such as replacing a broken booking URL are permitted; structural or content edits are not) + +### Post-Publish Defect +Any of the following after an approved change has been published, detected within 14 days of publication (or longer if the client reports later with clear attribution): +- The change is rejected or reversed by the platform (e.g., Google) +- The change introduces a new Verified error on the same field or a directly dependent field +- A client reports that the published state is incorrect or harmful +- The change violates the Low-Risk Fix criteria + +Any Post-Publish Defect immediately revokes graduation for that Task Type. + +### Shadow-Mode Graduation +A Task Type may only move from gated to auto-approved after a documented reliability window of human reviews with agreement ≥ X% and zero Post-Publish Defects. Criteria are set in an ADR. Graduation is per Task Type and is immediately revoked on any Post-Publish Defect. + +### Task Type +A unique pair of Owner + Surface. Graduation and revocation operate at this granularity only. + +### Proof-of-Concept Fix +A single, high-leverage, low-risk correction performed (with explicit approval) during the initial assessment phase to demonstrate value before a retainer is offered. Typical examples include correcting a broken booking URL or an incorrect GBP phone number. + +### Before/After Report +A client-facing document that shows the state of specific Findings before and after approved remediations, backed by hashed evidence. + +--- + +## Check System Terms + +### Check +A declarative test defined in specifications/checks/. Every Check must declare: id, domain, requires_human_approval (boolean), remediation_class, evidence_type, freshness_days. + +### Domain +One of: Customer Path Integrity, AI Visibility Integrity, Local Competitive Awareness. Must match the ownership table. + +### Remediation Class +How a failing Check is expected to be addressed: automated, guided, manual, or referral (blocked / out-of-scope). + +--- + +## Domain-to-Surface Ownership (V1) + +| Surface | Primary Domain | Notes | +|--------------------------|-----------------------------|-------| +| GBP core fields | Customer Path Integrity | Phone, hours, booking, services | +| Website contact paths | Customer Path Integrity | Forms, CTAs, booking links (single-attribute only for fixes) | +| Primary citations (NAP) | Customer Path Integrity | Consistency of name/address/phone | +| Structured data / schema | AI Visibility Integrity | FAQ, LocalBusiness, Service | +| Sampled AI answers | AI Visibility Integrity | Indicative only | +| Competitor signals | Local Competitive Awareness | Supporting | + +Shared surfaces declare a primary owner. Secondary domains may observe but do not own remediation. + +--- \ No newline at end of file