114 lines
4.0 KiB
Markdown
114 lines
4.0 KiB
Markdown
# 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.*
|