Kai Local Audit

Kai root note: knowledge/, harness/, and scripts/ paths in this skill live in the Kai install, not the user's project. Resolve them against the first ancestor directory of this SKILL.md that contains a knowledge/ folder (the Kai plugin root, ~/.claude/kai, or the kai-cmo-harness repo). MARKETING.md, memory/, and any output files live in the current project. If a referenced scripts/ command is not available in this install, say so, skip it, and continue with the file-based guidance — never fabricate its output.

/kai-local-audit — What a Local Business's Customers Actually See, and What to Do About It

Objective

An owner-facing report on one local business that shows how it looks from its customers' towns, phones and languages, backed by located data anyone can re-pull, and that converts each finding into a priced offer, an exact change and a dated week of a 12-week plan. When asked, a localized rerun for a named market and a translated sibling page with identical structure.

The report's value is that it is right about things the owner cannot see from their own laptop: which phones cannot open the site, who owns the map pack in the next town, what AI assistants recommend instead, what shipping really costs a customer.

Done when

Work type audit-report — floor E3/C4/O1 (harness/eco-floors.yaml), client_facing: true.

• E3 — the delivered report (and translated sibling, if requested) is the approved version, and every quantitative claim resolves to workspace/local-audit/<slug>/audit-data.json or a dated artifact in raw/.
• C4 — the Kai Data Provenance Rule in full: collector and local-audit pulls ran before writing, the mode is declared, _data-sources.md and _data-gaps.md exist, python scripts/quality_gates/audit_provenance_lint.py workspace/local-audit/<slug> --audit-dir passes, banned_word_check passes, and the rendered page has no horizontal overflow at 390 px or 1280 px outside table wrappers, no missing images, no duplicate ids.
• O1 — the targets table names today's value, the target, the pull that measures it and the re-run date. The outcome read is that re-run.

Constraints

Provenance — non-negotiable

• Load harness/references/audit-data-provenance.md. Mode is sales_external unless the client granted access.
• Run python -m scripts.audit.collect --url "<url>" --firm-name "<name>" --mode sales_external --workflow local-audit --out workspace/local-audit/<slug> before writing; scripts.local_audit.pulls and scripts.local_audit.checks append to the same dataset.
• No ranking, score or visibility claim from a personal browser session. Rankings, map packs and AI answers come from located API pulls (coordinates, mobile, market language). Speed scores come from the DataForSEO Lighthouse pull. The reference run's two eyeballed numbers were both wrong.
• Rankings move day to day: date every ranking claim and prefer counts across many located observations over a single position.
• Analytics totals are never reported raw. Split them into real visits and noise (storefront pixels, automation, developer machines, other hosts), report the cleaned figure, and mark that section onboarding_connected. Analytics cannot see visitors the site turns away, so it never overrides the access test.
• Share of estimated clicks is modeled (volume × positional CTR) and is labeled as modeled wherever it appears.
• A business recommended by an AI assistant, and any competitor positioning claim, is verified on that business's own site before it is repeated.
• Running the collector: the DataForSEO scripts ship in the Kai plugin (scripts/audit/, scripts/local_audit/, examples/local-audit-config.example.json) as well as the full harness. They are stdlib-only Python 3.10+. Run them as modules from the Kai root and point --out at an absolute path in the current project, e.g. OUT="$PWD/workspace/local-audit/<slug>"; cd "<kai-root>" && python -m scripts.local_audit.pulls balance --config "$OUT/config.json" --out "$OUT". Credentials come only from the environment: DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD (or DATAFORSEO_AUTH_B64). Never print them or write them into the audit folder.
• Every search runs in every language the market searches in: volumes, discovery seeds, located SERPs, Maps queries, AI prompts, and competitor, directory and press searches, with paired terms shown side by side. This is a research rule; a translated page is a separate request.
• Without DataForSEO credentials or scripts/local_audit/ in the install: direct public checks only, every located metric in _data-gaps.md, and the report header says located metrics need the full harness (github.com/cgallic/kai-cmo-harness).

Conduct

• Read-only on the web: no logins, follows, likes, messages, form submissions or orders. Shipping quotes come from a throwaway cart that is emptied afterwards.
• brand_pattern matches only the audited business; a loose pattern produces false "listing found" results.

Report

• First screen: 3–5 actions for this week, each with the exact URL, number, setting or line of code.
• Offers follow /kai-offer-builder doctrine and are priced on measured costs (shipping tiers, fees); every price is a proposal to check against costs; no margins that were not provided.
• Changes are grouped by who does them — code, copy in every market language, commerce admin, Google Business Profile, DNS, social and partner asks — and are exact enough to hand off.
• The 12-week plan starts the next Monday, splits owner and developer work, gives each week a "done when", and places seasonal work where the volume pull shows the peaks.
• Phone Capture Fit Rule: evaluate phone and follow-up capture; compare alternatives; say plainly when it is not the first fix.
• House voice: no announced lists, dramatic fragments, "not X but Y", or tricolons. Hosted pages are published privately on your own host: noindex,nofollow,noarchive, an unguessable URL, and no links from public pages.
• Internal economics never appear on a customer-facing page: your rates, margins, delivery costs, data spend, prospect scoring and sales notes stay in a separate internal file.
• A translated sibling keeps every tag, attribute and element in place; only visible text, alt, title, aria-label and meta description change; code, URLs, brand names and search queries shown as data stay as they are.

Revenue lens

Load the Revenue Lens section of harness/references/audit-data-provenance.md with the provenance rule.

• Open with the funnel, not activity. Traffic source → intent → lead → follow-up → booked/paid, one row per stage, before any channel or technical finding. Sessions and lead counts are inputs, never the headline.
• Rank gaps by the dollars each stage leaks. High-intent traffic with no lead path, leads with no follow-up, and follow-up with no booking outrank traffic volume.
• Technical setup is one line. Schema, llms.txt, AI crawler access and sitemap get a sourced pass/fail; they become findings only when a measured check fails.
• Unverified means check. Any claim or funnel stage not verified in this run is labeled check with what would verify it, is not scored, and is mirrored in _data-gaps.md.

Context

Output: workspace/local-audit/<slug>/ — config.json, audit-data.json, kai-data.json, _data-sources.md, _data-gaps.md, raw/ (API responses, direct-check artifacts, screenshots, shipping quotes), local-audit/ (per-pull summaries), report.html, and <lang>/report.html when translated.

Typical cost: about $8 of DataForSEO credit for two markets with crawl, reviews and AI answers; re-runs of cached pulls are free.

Escalate when

• DataForSEO credentials are missing or the balance cannot cover the planned pulls — say which metrics become data gaps.
• The business model or target market is ambiguous enough that the keyword set or vantage towns would change materially.
• A finding would require logging in, submitting a form or placing an order to confirm.
• The report will be sent to the business itself and includes pricing proposals the requester has not reviewed.