diff --git a/docs/operations/client-intake-audit-alignment.md b/docs/operations/client-intake-audit-alignment.md new file mode 100644 index 0000000..432ed9e --- /dev/null +++ b/docs/operations/client-intake-audit-alignment.md @@ -0,0 +1,113 @@ +# Client Intake ↔ Audit Record Alignment Directive + +**Status:** Active +**Created:** 2026-08-11 +**Purpose:** Ensure every data point captured during an audit maps cleanly and identically into the client intake form / Google Sheet structure, and that human verification is required wherever automation is unreliable or judgment is needed. + +--- + +## Core Principle + +The Google Sheet (or future intake form) is the **operational front door**. +Gitea is the **versioned source of truth**. + +Every field we capture in an audit must either: + +1. Map directly to a column in the Clients intake sheet, or +2. Be stored in a structured raw/analysis file in the client’s Gitea repo that can later feed the intake or reports. + +No orphan data. No free-form notes that cannot be traced back to a required field. + +--- + +## Required Intake Fields (must stay in sync) + +These columns in the **Clients** Google Sheet are the minimum contract: + +| Field | Required | Notes | +|-------|----------|-------| +| Client ID | Yes | e.g. VP-001 | +| Business Name | Yes | Exact string | +| Website | Yes | Canonical URL | +| Primary Address | Yes | Street + Suite | +| City | Yes | | +| State | Yes | | +| Phone | Yes | Full digits preferred | +| Contact Email | Yes | | +| Primary Category | Yes | | +| Main Services | Yes | High-level list | +| Competitors | Preferred | | +| Intake Date | Yes | | +| Last Audit Date | Yes (after first audit) | | +| Next Review Date | Yes (after first audit) | | +| Status | Yes | Controlled vocabulary | +| Ground Truth Score | After audit | Human judgment | +| AI Visibility Summary | After interrogation | | +| Priority Issues | After analysis | | +| Report Link | When report exists | | +| Notes | Optional | | +| Last Updated | Yes | | + +Any new field added to the Sheet must be reflected here and in the relevant Gitea templates. + +--- + +## Human Verification Rules + +**Human eyes are mandatory** before a data point is marked as Ground Truth when any of the following are true: + +- Sources conflict (e.g. website hours ≠ Yelp hours ≠ Google hours) +- The value is subjective or requires judgment (score, priority, tone, quality) +- Automation/scraping is known to be unreliable for that source +- The field affects client-facing recommendations or remediation +- The data will be used to generate schema, GBP rewrites, or reports + +**Status vocabulary for raw captures** (already in use): + +- `NOT_PRESENT` — looked and confirmed absent +- `NOT_OBSERVED` — did not look or could not see +- `Unknown` — looked but signal is ambiguous +- Concrete observed value + +Agents may propose values. Humans must approve before the value is written as final Ground Truth into the client repo or the intake Sheet. + +--- + +## Process Flow (current simple version) + +1. **Intake** → Client row created in Google Sheet (manual or form) +2. **Raw capture** → Structured snapshots written to the client’s Gitea repo (`raw/`) +3. **Human review** → Conflicts resolved, scores assigned, priority issues named +4. **Ground Truth locked** → Clean values promoted to the intake Sheet + analysis files +5. **Remediation / Report** → Generated only from locked Ground Truth + +--- + +## Hermes / Agent Role + +Agents (including any future Hermes Office suite capabilities) may: + +- Pull and structure public data +- Fill draft templates +- Flag conflicts +- Propose values + +Agents may **not**: + +- Mark a conflicting or judgment-based field as final Ground Truth without human confirmation +- Write directly to the live client intake Sheet without an explicit approval step + +If Hermes Office suite later gains reliable form-filling ability, it must still respect the human-verification gate defined above. + +--- + +## Immediate Next Actions + +- Keep the Clients Google Sheet columns as the source of the field contract +- Continue walking Phoenix Salon + Spa using this alignment +- After each major section is human-verified, write the clean record into `client-data-pss` +- Update this directive if new required fields are added + +--- + +*This directive supersedes informal process notes for client intake and audit record structure.*