our-claude-skills/custom-skills/95-ourdigital-presales-seo/DESIGN.md

Design — ourdigital-presales-seo skill

• Status: Approved design (2026-05-27). Ready for implementation planning.
• Author: OurDigital (andrew.yim@ourdigital.org)
• Origin: Standardizes the Sono Hotels & Resorts pre-sales diagnostic (~/Workspaces/shr-workspace/audits/2026-05-27-presales/) into a reusable skill, adding estimate generation and a sales slide deck.

1. Purpose & scope

A single OurDigital Claude Code skill that runs a pre-sales SEO + entity diagnostic for any prospect domain and produces, as confirmed step-by-step stages:

1. Technical / on-page scan
2. Knowledge Graph / entity analysis (Korean market, Naver-aware)
3. Consolidated opportunity brief
4. Rate-card-based cost estimate (견적)
5. Editable PPTX sales-briefing deck + short client PDF

Public-data only by default (no client GSC/GA4/GTM access assumed) — suited to prospecting where access isn't yet granted.

Non-goals (YAGNI)

• Not a full post-contract audit (that stays with seo-comprehensive-audit).
• No fixed 3-tier package output (user chose findings→rate-card line items only).
• No automated sending/emailing of deliverables.
• No fully-autonomous mode — execution is step-by-step gated.

2. Invocation & inputs (Stage 0)

Invoked as /ourdigital-presales-seo (optionally with a domain arg). Stage 0 gathers:

Input	Req	Default
domain	✅	—
brand_name + aliases[] (for KG; e.g. 앤/& /EN variants)	✅	derived from site <title>/og
sub_brands[], properties[] (entity targets)	—	auto-extracted from crawl URL patterns
competitors[]	—	from references/competitor_sets.md by vertical
market / language	—	South Korea / ko (Naver-aware)
output_dir	—	account workspace if exists, else seo-workspace/prospecting/<date>-<prospect>/ (see §7)
vertical	—	inferred (hotel/resort default rubric)

Stage 0 also runs a preflight tool check (Firecrawl, DataForSEO, GOOGLE_KG_API_KEY, headless Chrome, python-pptx) and reports any missing capability with its fallback.

3. Pipeline (step-by-step; each stage presents results and WAITS for user confirmation)

Stage	Actions	Primary tools	Output
0 Scope	inputs, folders, preflight	—	scope.md, folders
1 Discovery	robots.txt, sitemap status, firecrawl_map inventory, scale estimate, URL hygiene (/test, params, dup /sb↔/brand_loc)	Firecrawl, WebFetch	data/urls.json, scan §1
2 Technical/on-page	JSON-LD extraction, meta/title/H1 duplication, hreflang completeness, CWV (Lighthouse)	Firecrawl scrape, DataForSEO Lighthouse	01_technical-onpage-scan.md, data/cwv_lighthouse.json
3 KG/entity	KG API (ko) over master/parent/legacy/membership/sub-brand/property/competitor sets; live SERP panel verification	kg_query.py (Google KG API), DataForSEO SERP	02_knowledge-graph-entity.md, data/kg_*.json, data/serp_panels_findings.md
4 Brief	synthesize, severity ranking, competitive gap table	—	03_presales-opportunity-brief.md
5 Estimate	findings→rate card mapping → ranged 견적	estimate.py + rate_card.yaml	05_estimate_ko.md, 05_estimate.xlsx — review gate
6 Deliverables	short client PDF + branded PPTX deck	render_pdf.sh (Chrome), build_deck.py (python-pptx)	client-brief.pdf, sales-deck.pptx — review before send
7 Archive	push consolidated report (03 brief + estimate summary) to the OurDigital SEO Audit DB — standard final stage	notion_writer.py	Notion row in SEO Audit Log

Each stage appends to the shared findings.json data contract (§5), the integration seam between analysis and the estimate/deck generators.

Archive target (standard): every run archives to the OurDigital SEO Audit database 2c8581e5-8a1e-8035-880b-e38cefc2f3ef (https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef). Row title <프로스펙트> SEO 사전진단 (Pre-sales) — <YYYY-MM-DD>; set Target URL, Audit Date, Account Code. This is the system of record for prospect + client audits alike.

4. Component breakdown (units & interfaces)

• SKILL.md — orchestration: stage definitions, per-stage gating, Korean-first output rules, tool fallbacks, sandbox-disable notes for KG/Chrome/Notion network calls.
• scripts/kg_query.py — IN: entity list (group,label,query) + lang + key (env). OUT: kg_raw.json, kg_flat.json, console summary (score/type/lodging-flag/own-entity). Generalized from the SHR script (entities parameterized, not hardcoded).
• scripts/estimate.py — IN: findings.json + rate_card.yaml + rules. OUT: 05_estimate_ko.md + 05_estimate.xlsx (항목·상세·수량·단가 range·금액; one-time + monthly subtotals; OD-YYYY-NNN; disclaimer) and data/estimate.json (selected line items + totals, consumed by build_deck.py).
• scripts/build_deck.py — IN: findings.json + estimate.json + deck_theme. OUT: sales-deck.pptx (9 slides, §6). python-pptx.
• scripts/render_pdf.sh — IN: client-brief HTML. OUT: PDF via headless Chrome (Korean system fonts).
• references/rate_card.yaml — single source of OurDigital service rates (see §5.1).
• references/findings_to_service.md — finding-class → severity → service-line rubric (§5.2).
• references/competitor_sets.md — default KR competitor benchmarks by vertical (hotel/resort seeded: 롯데/신라/조선/한화/켄싱턴).
• templates/ — 01/02/03 md, client_brief.html, estimate_OD.md, deck_theme.py.

5. Estimate logic

Superseded (2026-05-28): the flat per-service ranges below were replaced by an effort-based engine (role-hours × billing_rate 0.70) loaded from OurDigital's real quotation templates. See references/rate_card.yaml, references/sow_templates.yaml, and references/findings_to_service.md. Validated to reproduce the real Basic (₩10.5M) and Treatment (₩25.0M) quotes exactly. The notes below are kept as historical context.

5.1 rate_card.yaml (from ourdigital-backoffice)

quote_prefix: OD            # OD-YYYY-NNN
currency: KRW
services:
  technical_audit:   {label: "Technical Audit / 기술 SEO 진단", unit: one_time, min: 3000000, max: 5000000}
  technical_remediation: {label: "기술 개선 실행", unit: project, min: 3000000, max: 8000000}
  onpage_entity:     {label: "On-Page / Entity Optimization", unit: monthly, min: 1500000, max: 3000000}
  schema_build:      {label: "구조화 데이터 구축(1회)", unit: one_time, min: 2000000, max: 4000000}
  local_seo:         {label: "Local SEO", unit: monthly, min: 1000000, max: 2000000}
  gtm_setup:         {label: "GTM Setup", unit: project, min: 2000000, max: 4000000}
  ga4_impl:          {label: "GA4 Implementation", unit: project, min: 1500000, max: 3000000}
  dashboard:         {label: "Dashboard Development", unit: project, min: 3000000, max: 6000000}

(Values mirror the backoffice rate card; treated as estimate ranges. Skill reads this file — no hardcoded prices.)

5.2 findings_to_service.md rubric (finding class → service line)

Finding class (from findings.json)	Service line(s)	Scope driver
broken sitemap / low crawl-coverage / SPA rendering / CWV poor	technical_audit + technical_remediation	site size, # templates
missing/weak schema, entity gaps, sub-brand/property entities, Wikipedia/sameAs	schema_build (one-time) + onpage_entity (retainer)	# sub-brands + # properties
property local packs / GBP-URL mismatch	local_seo	# properties
no GSC/GA4, measurement gaps	ga4_impl and/or dashboard, gtm_setup	—
duplicate meta / title i18n / hreflang / content confusion	onpage_entity	# templates

estimate.py selects line items per detected findings, scales qty by drivers (e.g., property count → local-SEO months/scope), sums one-time vs monthly, and renders the 견적. Always includes the disclaimer: ranges; finalized after a precise diagnostic with GSC/GA4 access.

6. PPTX deck spec (build_deck.py, 9 slides)

1. Title — prospect + "검색 가시성 사전 진단" + date + OurDigital
2. 한눈에 보기 — asset strength vs search-visibility gap
3. Finding 1 — 크롤/색인 (sitemap, discoverable-URL count)
4. Finding 2 — Core Web Vitals
5. Finding 3 — 엔티티/브랜드 인식 (entity type, name split, legacy contamination)
6. Finding 4 — 서브브랜드/프로퍼티 엔티티 + 경쟁 벤치마크 table
7. 개선 로드맵 — Phase 0 (긴급 기술) / 1 (엔티티) / 2 (콘텐츠·로컬)
8. 예상 견적 — rate-card line items + ranges + disclaimer
9. 다음 단계 / CTA — 30분 미팅 · 정밀 진단 · 파일럿

Branding from ourdigital-brand-guide (colors/fonts/logo); fallback theme = navy #11243d / accent #1b6fb3 (the SHR brief styling). Slides are content-populated from findings.json + estimate.json, leaving text editable.

7. Output routing

Default: if ~/Workspaces/<slug>-workspace/ exists → …/audits/<YYYY-MM-DD>-presales/; else ~/Workspaces/seo-workspace/prospecting/<YYYY-MM-DD>-<prospect>/ (per global routing rule). Overridable at Stage 0. data/ holds raw artifacts; audit md + deck/PDF at top level.

8. Dependencies & documented fallbacks

Capability	Tool	Fallback / gotcha
URL inventory	Firecrawl map	OurSEO crawl_website caps ~60 pages regardless of max_pages; broken sitemap limits discovery — report the discoverable count as a finding
Page signals	Firecrawl scrape (json)	re-scrape if cache returns empty
SERP panels / CWV	DataForSEO serp_organic_live_advanced, on_page_lighthouse	—
Entity DB	Google KG Search API	needs GOOGLE_KG_API_KEY / GOOGLE_API_KEY; sandbox-disable for network
Client PDF	headless Chrome --print-to-pdf	needs Korean system font (AppleSDGothicNeo present on macOS); sandbox-disable
Deck	python-pptx	install if missing
Notion archive	notion_writer.py → DB 2c8581e5-8a1e-8035-880b-e38cefc2f3ef	use --properties with Target URL/Audit Date/Account Code only; Audit ID is a read-only formula (do not set); Site/Found Date from old docs are wrong property names

9. Data contract — findings.json (analysis ↔ generators seam)

{
  "prospect": {"name": "", "domain": "", "aliases": [], "vertical": ""},
  "discovery": {"sitemap_status": 500, "robots_sitemap_declared": false,
                "discoverable_urls": 96, "estimated_pages": "thousands",
                "url_hygiene": ["test_page_exposed", "dup_path_scheme", "param_urls"]},
  "technical": {"cwv": {"lcp_ms":0,"cls":0,"ttfb_ms":0,"perf":0},
                "schema": {"org": "bare|complete|none", "hotel_on_property": true},
                "meta_dupe": true, "title_i18n_mismatch": true, "hreflang": "incomplete"},
  "entity": {"panel": "company|hotel|none", "name_split": true, "legacy_contamination": true,
             "subbrands_with_entity": 0, "properties_with_entity": 0,
             "competitor_benchmark": [{"name":"","score":0,"type":"","wikipedia":false}]},
  "findings": [{"id":"", "class":"", "severity":"critical|high|medium", "evidence":"", "recommended_services":[]}]
}

Stages 1–4 populate it; Stages 5–6 consume it. This is the key isolation boundary: generators never re-crawl.

10. Validation

• Dry-run on the SHR data (already collected) → estimate + deck must reproduce sensible output.
• kg_query.py unit check: known entity (롯데호텔) returns LodgingBusiness + high score.
• Deck opens in PowerPoint/Keynote; Korean renders; placeholders editable.
• Estimate totals = sum of selected line items; disclaimer present.

11. Future (out of scope now)

3-tier package view; auto Naver SERP module; multi-language decks; CRM hand-off.