Content Authority v1.0

# Content Authority — OGSM Definition

> Version: 1.0
> Created: 2026-05-20
> Fleet: standalone
> 3-Model Eval: Median 8.6/10 (Codex 8.0, Sonnet 9.2)
> Consolidates: w-emailcontent + blog-writer-fleet + geo-authority S1

## Tier 1 Summary

G: Audience shifts from "never heard of Waterson" to "this is where I go for
door hardware compliance answers" — measured by AI citations ≥15/mo, SEO
traffic +50%, AI crawler visits +100%, return visitor rate ≥15%.

S: Mine topics from real customer emails (preserving raw quotes + threadId),
write with ≥3 P0 regulatory citations per article via Claim Bank,
batch-rewrite all existing pages validated by AI Citation Willingness Test.

M: Resource Check — source-material.md with threadId exists, claim-bank.json
returned >0, 3 Python validators exit 0. Outcome Check — 3-Model blind eval
median ≥8.0 (2hr budget), 3 Persona Q7=YES, AI says "I would cite this" ≥2/3.

## O

建築師和設施管理者在查門控五金法規合規問題時，Waterson 是他們第一個找到、
也最信任的來源 — 因為每篇內容的法規引用深度和專業權威性，讓人覺得
「這就是業界標準答案」。

## G

| # | Goal | Baseline | Target | Deadline |
|---|------|----------|--------|----------|
| G1 | AI engine citations | ~5/mo | ≥15/mo | 2026-12-31 |
| G2 | SEO organic traffic | current avg | +50% | 2026-12-31 |
| G3 | AI crawler weekly visits | current avg | +100% | 2026-12-31 |
| G4 | Return visitor rate (30d ≥2x) | untracked | ≥15% | 2027-03-31 |

## S

S1: Mine topics from real customer conversations, preserve email raw content
S2: Embed ≥3 P0 regulatory citations per article via Claim Bank
S3: Batch-rewrite ALL existing pages to AI-citable format (Phase 1 in 2 weeks)

## M

Resource Check (per S):
- S1: source-material.md exists with threadId per article
- S2: claim-bank.json returned >0, ≥3 P0 citations, 3 validators exit 0
- S3: AI Citation Willingness Test run per page (3 models asked)

Outcome Check (per S):
- S1: Topic → publish rate ≥50% (quarterly)
- S2: 3-Model blind eval median ≥8.0 (2hr budget), Persona Q7 all YES
- S3: ≥2/3 AI models say "I would cite this", crawler visits +50% post-rewrite

---
name: source-preserving-extract
description: >
  Extract article source material from a customer email thread, preserving raw quotes verbatim and recording the Gmail threadId.
user-invocable: false
---

# Source-Preserving Extract

## Purpose
Extract structured source material from a customer email task object. Raw customer quotes must be preserved verbatim — they are the authentic signal that grounds every article. The Gmail threadId is captured here so every downstream artifact can trace back to the originating conversation (CA-02 blocking rule).

## Load context first
1. `docs/waterson-wiki/communication-rules.md` — anonymization rules and tone policy
2. `docs/waterson-wiki/product-facts.md` — product terminology to recognize in emails
3. `.claude/skills/content-authority/policies/scan-contract.md` — required fields for output files

## Instructions
1. Receive a task object from `data/topic-inbox.json` (fields: `threadId`, `sender_role`, `subject`, `body_text`, `signal_strength`).
2. Read `communication-rules.md` to confirm anonymization rules before touching any sender data.
3. Extract the following from `body_text`:
   - **Persona**: infer role from context (e.g., "a facility manager", "an architect") — never use sender name or company.
   - **Core question**: the primary information need expressed by the customer (one sentence).
   - **Raw quotes**: every sentence that contains a specific concern, confusion, or requirement. Copy verbatim — do NOT paraphrase.
   - **Regulatory touchpoints**: any standards or codes mentioned (e.g., NFPA 80, ADA, ANSI A156.19, IBC, UL 10C). Record exact strings.
   - **Product signals**: any Waterson product features or specs mentioned.
4. Verify `threadId` is present. If missing, abort with error: `MISSING_THREAD_ID`.
5. Write output to `data/source-materials/{slug}/source-material.md` using the format below.
6. Do NOT modify `topic-inbox.json` — that is the responsibility of `infra/content-plan-sync`.

## Output format
```markdown
# Source Material: {slug}

## Metadata
- threadId: {gmail_thread_id}
- signal_strength: HIGH | MEDIUM
- persona: {anonymized_role}
- extracted_at: {ISO8601 timestamp}

## Core Question
{One sentence describing the customer's primary information need}

## Raw Customer Quotes
> "{verbatim quote 1}"
> "{verbatim quote 2}"


## Regulatory Touchpoints
- {standard 1} (e.g., NFPA 80 Section 4.1)
- {standard 2}

## Product Signals
- {feature or spec mentioned by customer}

## Anonymization Notes
- Sender anonymized as: {persona label used}
```

## What this skill does NOT do
- Does not scan Gmail or HubSpot
- Does not research regulatory standards — that is `composite/research-topic`
- Does not write or outline articles
- Does not evaluate content quality
- Does not update `content-plan.md` or `topic-inbox.json`
- Does not use AI to rewrite or summarize quotes — verbatim only

## Closing action
Report: `source-material.md` written to `data/source-materials/{slug}/`. Confirm threadId recorded. Pass slug to `core/claim-bank-builder` as next step.

---
name: claim-bank-builder
description: >
  Run the deterministic Python script to build a claim bank from regulatory touchpoints — zero AI tokens consumed.
user-invocable: false
---

# Claim Bank Builder

## Purpose
Build a structured claim bank by running `scripts/build_claim_bank.py` — a deterministic Python script that parses regulatory standards. This skill uses zero AI tokens by design (CA-05). No article may be written until a valid claim bank exists for its topic (CA-06 gate). Only NFPA, ADA, ANSI, IBC, and UL are accepted as P0 regulatory citation sources.

## Load context first
1. `data/source-materials/{slug}/source-material.md` — regulatory touchpoints list (required input)
2. `scripts/build_claim_bank.py` — understand expected arguments and output schema
3. `.claude/skills/content-authority/policies/citation-policy.md` — P0 vs P1 classification rules

## Instructions
1. Read `source-material.md` for the given slug. Extract the `Regulatory Touchpoints` list.
2. Validate each touchpoint against allowed P0 sources: NFPA, ADA, ANSI (A156.x series), IBC, UL.
3. Run the claim bank script:
   ```bash
   python3 scripts/build_claim_bank.py \
     --slug "{slug}" \
     --touchpoints "{comma-separated touchpoints}" \
     --output "data/source-materials/{slug}/claim-bank.json"
   ```
4. Verify the script exits with code 0. If non-zero, report the error and abort.
5. Count P0 claims.
6. Gate check (S2): if P0 claim count < 3, abort with: `INSUFFICIENT_P0_CLAIMS`.
7. Report claim counts by tier (P0 / P1 / P2) to the calling skill.

## Output format
```json
{
  "slug": "fire-door-self-closing-requirements",
  "generated_at": "2026-05-21T08:00:00Z",
  "p0_count": 5,
  "p1_count": 3,
  "claims": [
    {
      "tier": "P0",
      "standard": "NFPA 80",
      "section": "4.1.2",
      "claim": "Fire doors in means of egress must be self-closing or automatic-closing.",
      "verbatim_text": "...",
      "source_url": "https://..."
    }
  ]
}
```

## What this skill does NOT do
- Does not use any AI model — all computation is deterministic Python
- Does not write or draft articles
- Does not accept non-P0 sources (Wikipedia, manufacturer specs, blog posts) as claims
- Does not update `content-plan.md` or `topic-inbox.json`

## Closing action
Report: `claim-bank.json` written with {n} P0 claims. If gate passed (≥3 P0), confirm readiness for `composite/write-article`. If failed, return error to calling skill with specific gap details.

---
name: fact-check
description: >
  Verify an article draft against claim-bank.json, waterson-wiki, and corrections-log using three Python validators followed by a Gemini Pro semantic check.
user-invocable: false
---

# Fact Check

## Purpose
Run a two-phase verification pipeline on a draft article. Phase 1 uses three deterministic Python validators (zero AI tokens). Phase 2 uses Gemini Pro for semantic accuracy checks. Every CRITICAL finding blocks publication. This skill is the factual firewall — it does not rewrite, only judges.

## Load context first
1. `data/source-materials/{slug}/claim-bank.json`
2. `docs/waterson-wiki/product-facts.md`
3. `docs/waterson-wiki/corrections-log.md`
4. `docs/waterson-wiki/communication-rules.md`
5. `tools/scripts/validate_citations.py`
6. `tools/scripts/validate_specs.py`
7. `tools/scripts/validate_corrections.py`

## Instructions

### Phase 1 — Deterministic Python validators (run all three)
1. Run `validate_citations.py --draft ... --claim-bank ...`
2. Run `validate_specs.py --draft ... --wiki ...`
3. Run `validate_corrections.py --draft ... --corrections ...`
4. All three must exit 0. Any non-zero exit = automatic CRITICAL failure.

### Phase 2 — Gemini Pro semantic check
5. Only proceed if all Phase 1 scripts pass.
6. Send draft + claim bank + communication-rules to Gemini Pro:
   ```bash
   gemini -m gemini-2.5-pro -p "$(cat .../fact-check-semantic.txt)"
   ```
7. Gemini evaluates: context accuracy, unsupported claims, communication rules violations.

### Severity classification
- **CRITICAL**: wrong spec value, repeat corrections-log error, citation out of context. Blocks publication.
- **WARNING**: imprecise language, unsupported minor claim. Requires revision.
- **INFO**: style suggestion. Optional.

8. Aggregate findings into `data/drafts/{slug}/fact-check-report.json`.

## What this skill does NOT do
- Does not rewrite or suggest rewrites — findings only
- Does not evaluate tone, readability, or SEO
- Does not run the 3-Model blind evaluation

## Closing action
Write `fact-check-report.json`. Report overall PASS/FAIL, findings by severity. If FAIL, pass findings to `composite/validate-article` for routing to revision loop.

---
name: persona-review
description: >
  Simulate three reader personas evaluating an article draft via Gemini Pro; all three must answer Q7=YES to pass the gate.
user-invocable: false
---

# Persona Review

## Purpose
Simulate how three real-world reader types experience the article before it reaches any actual customer. Each persona answers 7 structured questions. The Q7 gate (CA-07) is a mandatory publication blocker: if any persona answers Q7=NO, the article must be revised. Q5 enforces the angle-gate policy.

## Load context first
1. `data/drafts/{slug}/draft.md`
2. `docs/waterson-wiki/communication-rules.md`
3. `.claude/skills/content-authority/policies/persona-definitions.md`

## Instructions
1. Load three persona profiles: Architect, Facility Manager, Contractor.
2. For each persona, run Gemini Pro with the 7-question rubric:
   ```bash
   gemini -m gemini-2.5-pro -p "$(cat .../persona-{role}.txt)"
   ```
3. Collect Q1-Q7 answers for each persona.
4. **Q7 gate**: any Q7=NO → overall FAIL. Collect NO reason as revision directive.
5. **Q5 angle-gate**: "helping" or "mostly helping" = acceptable. "selling" = WARNING.
6. Write all answers + gate result to `data/drafts/{slug}/persona-review.json`.

## 7-Question Rubric
| # | Question |
|---|----------|
| Q1 | Does the opening directly address your real-world concern? |
| Q2 | Are the regulatory citations accurate and relevant to your jurisdiction? |
| Q3 | Is the technical depth appropriate for your expertise level? |
| Q4 | Are there any claims you would challenge or verify independently? |
| Q5 | Does this feel like it's helping you or selling to you? |
| Q6 | Is there anything important missing that you expected to find here? |
| Q7 | Would you bookmark this page or share it with a colleague? (YES/NO) |

## What this skill does NOT do
- Does not check factual accuracy — that is `core/fact-check`
- Does not rewrite or modify the article
- Does not run the 3-Model blind evaluation
- Does not simulate more than 3 personas

## Closing action
Write `persona-review.json`. Report gate status. If Q7 FAILED, extract NO reasons as revision instructions for `composite/validate-article`.

---
name: mine-topics
description: >
  Morning pipeline that reads topic-inbox.json and calls source-preserving-extract for each HIGH/MEDIUM signal item.
user-invocable: false
---

# Mine Topics

## Purpose
Convert raw topic signals from the morning digest into structured source-material files ready for article development. Bridge between the email-scanning world (gmail-reply-extension) and the content-creation world. Respects the scan-contract — never modifying topic-inbox.json directly.

## Load context first
1. `data/topic-inbox.json` — morning digest output
2. `.claude/skills/content-authority/policies/scan-contract.md`
3. `docs/waterson-wiki/product-facts.md`

## Instructions
1. Read `data/topic-inbox.json`. Verify file exists and is valid JSON.
2. Filter by `signal_strength`: keep only HIGH and MEDIUM. Skip LOW and SPAM.
3. For each qualifying item, check if `data/source-materials/{slug}/source-material.md` already exists.
   - If exists and status is not `stale`, skip.
   - If not exists or marked `stale`, proceed.
4. For each item to process, call `core/source-preserving-extract`.
5. On success, record slug as extracted. On failure (e.g., `MISSING_THREAD_ID`), log error and continue.
6. Generate summary report.

## Output format
```json
{
  "run_at": "2026-05-21T07:30:00Z",
  "inbox_items_total": 12,
  "qualifying_items": 7,
  "processed": 5,
  "skipped_existing": 2,
  "errors": [{"threadId": null, "subject": "Door question", "error": "MISSING_THREAD_ID"}],
  "source_materials_created": ["data/source-materials/fire-door-gap-requirement/source-material.md"]
}
```

## What this skill does NOT do
- Does not scan Gmail or HubSpot
- Does not write articles or outlines
- Does not update `topic-inbox.json` — only reads it
- Does not call `core/claim-bank-builder`

## Closing action
Report {n} source-material files extracted. Pass slug list to `infra/content-plan-sync`.

---
name: research-topic
description: >
  Deep research for a specific topic using Gemini Pro with search grounding, producing a research-context.md for the writer.
user-invocable: false
---

# Research Topic

## Purpose
Build rich research context that gives the article writer accurate, current, and well-organized background material. Gemini Pro with search grounding goes beyond static wiki knowledge — finding recent code updates, court cases, and competitor coverage gaps.

## Load context first
1. `data/source-materials/{slug}/source-material.md`
2. `data/source-materials/{slug}/claim-bank.json`
3. `docs/waterson-wiki/product-facts.md`
4. `.claude/skills/content-authority/policies/research-scope.md`

## Instructions
1. Read `source-material.md`: extract core question, regulatory touchpoints, persona.
2. Read `claim-bank.json`: note which standards have P0 claims — research deepens these, not duplicates.
3. Construct research queries:
   - **P0 standard deep dive**: NFPA/ADA/ANSI/IBC/UL sections, 2026 update status, enforcement guidance.
   - **Industry context**: how practitioners apply requirements in real projects.
   - **Competitor coverage**: what top-ranking pages say, what their gaps are.
   - **Recent changes**: amendments, interpretations, enforcement trends in the past 24 months.
4. Run Gemini Pro for each query area:
   ```bash
   gemini -m gemini-2.5-pro -p "Research the following for a technical article targeting {persona}: {query}"
   ```
5. Organize findings by standard (not by query).
6. Flag any finding contradicting an existing P0 claim — requires human review.
7. Write output to `data/source-materials/{slug}/research-context.md`.

## What this skill does NOT do
- Does not write articles or create outlines
- Does not check facts in existing drafts
- Does not modify `claim-bank.json`

## Closing action
Write `research-context.md`. Report: standards covered, competitor gaps found, claim contradictions flagged. Signal readiness for `composite/write-article`.

---
name: write-article
description: >
  Write an article draft using Claude Opus, embedding ≥3 P0 regulatory citations with SEO and AEO structure.
user-invocable: false
---

# Write Article

## Purpose
Produce a complete, publication-ready article draft that answers the customer's core question with regulatory authority. Claude Opus is required for language quality. Draft must embed ≥3 P0 claims from the claim bank (S2) and follow the angle-gate policy: readers feel helped, not sold to.

## Load context first
1. `data/source-materials/{slug}/source-material.md`
2. `data/source-materials/{slug}/claim-bank.json` — P0 claims to embed (minimum 3, S2)
3. `data/source-materials/{slug}/research-context.md`
4. `docs/waterson-wiki/product-facts.md`
5. `docs/waterson-wiki/communication-rules.md`
6. `.claude/skills/content-authority/policies/article-structure.md`
7. `.claude/skills/content-authority/policies/seo-aeo-checklist.md`

## Instructions
1. Verify all required input files exist. If `claim-bank.json` missing or P0 count < 3, abort: `CLAIM_BANK_GATE_FAILED`.
2. Read core question from `source-material.md`.
3. Design article structure: H1 answers/frames the core question, H2s per major sub-question, FAQ ≥3 questions.
4. Write with Claude Opus:
   - Embed ≥3 P0 citations with section references (not just standard names)
   - Positive framing: reader learns what to do, not what they're doing wrong
   - Technical depth matched to persona
   - Use customer's raw quotes to inform tone — they are anonymized context, not direct quotes
5. Check against angle-gate: "Is this helping or selling?" Flag selling-oriented paragraphs.
6. Add SEO metadata block and AEO structured data.
7. Save draft to `data/drafts/{slug}/draft.md`.

## What this skill does NOT do
- Does not research standards — that is `composite/research-topic`
- Does not fact-check the draft it produces
- Does not run the 3-Model blind evaluation
- Does not publish or deploy
- Does not use GPT-4 or Gemini for writing — Claude Opus only

## Closing action
Save `draft.md`. Report: word count, P0 citations embedded, H2 structure. Signal `composite/validate-article`.

---
name: validate-article
description: >
  Orchestrate the full validation pipeline: fact-check → persona-review → 3-Model blind eval, routing failures back to write-article.
user-invocable: false
---

# Validate Article

## Purpose
Quality gate orchestrator between writing and publishing. Calls three specialized sub-skills in sequence and aggregates results. Any failure produces structured revision instructions routed back to `composite/write-article`. 3-Model blind eval has 2-hour budget, must reach median ≥8.0.

## Load context first
1. `data/drafts/{slug}/draft.md`
2. `data/source-materials/{slug}/claim-bank.json`
3. `.claude/skills/content-authority/policies/eval-rubric.md`

## Instructions

### Step 1 — Fact Check
1. Call `core/fact-check`. Read `fact-check-report.json`.
2. If FAIL: extract CRITICAL findings, format as revision instructions. Go to Step 4.
3. If PASS: proceed to Step 2.

### Step 2 — Persona Review
4. Call `core/persona-review`. Read `persona-review.json`.
5. If Q7 gate FAIL: extract Q7=NO reasons, format as revision instructions. Go to Step 4.
6. If PASSED: proceed to Step 3.

### Step 3 — 3-Model Blind Evaluation (CA-04, 2hr budget)
7. Send draft to three models independently:
   - Claude Sonnet / Claude Haiku / Gemini Pro
8. Each model scores 1-10 on each rubric dimension.
9. Calculate median of three total scores.
10. If median < 8.0: extract lowest-scoring dimensions, format as revision instructions. Go to Step 4.
11. If median ≥ 8.0: Step 3 passes.

### Step 4 — Route to revision (if any step failed)
12. Compile all revision instructions.
13. Write `validation-report.json` with status=FAIL.
14. Return instructions to `composite/write-article`. Max 3 cycles — then escalate to human.

### Step 5 — All steps passed
15. Write `validation-report.json` with status=PASS.
16. Signal `composite/publish-article`.

## What this skill does NOT do
- Does not write or rewrite content
- Does not run fact-checking logic directly — delegates to `core/fact-check`
- Does not run persona simulation directly — delegates to `core/persona-review`
- Does not publish or deploy

## Closing action
Write `validation-report.json`. PASS → notify `composite/publish-article`. FAIL → send revision instructions with cycle count. Cycle > 3 → escalate with full history.

---
name: publish-article
description: >
  HTML assembly and deployment pipeline: md-to-html conversion, sitemap update, content-plan registration, and blog directory copy.
user-invocable: false
---

# Publish Article

## Purpose
Convert a validated article draft to production HTML files and deploy to the blog directory. All conversion is deterministic Python (CA-05, zero AI tokens). Source metadata including the originating Gmail threadId is registered in content-plan.md (CA-08) for full traceability.

## Load context first
1. `data/drafts/{slug}/draft.md` — must have PASS validation-report
2. `data/drafts/{slug}/validation-report.json`
3. `tools/scripts/md-to-html.py`
4. `sitemap.xml`
5. `content-plan.md`
6. `.claude/skills/content-authority/policies/publish-checklist.md`

## Instructions
1. Verify `validation-report.json` exists and `overall_status` = `PASS`. Abort otherwise.
2. Read slug metadata from `source-material.md` (threadId, signal_strength, persona).

### Step 1 — HTML conversion
3. Run md-to-html for EN, ZH, and AEO versions (0 AI tokens).
4. Verify all three scripts exit 0.

### Step 2 — Sitemap update
5. Append three URLs: `/blog/{slug}/`, `/blog/{slug}/zh/`, `/blog/{slug}/aeo/`.
6. Update `lastmod`.

### Step 3 — content-plan.md registration (CA-08)
7. Call `infra/content-plan-sync` with: source_type, signal_strength, source_ids (threadId), topic, status=published, published_at, urls.

### Step 4 — Verification
8. Confirm all three HTML files exist.
9. Confirm sitemap contains all three new URLs.
10. Confirm content-plan shows status=published.

## What this skill does NOT do
- Does not write or generate any text content
- Does not validate article quality
- Does not generate Chinese translation — `draft-zh.md` must exist beforehand
- Does not push to Git or trigger Vercel — that is `/upload` skill

## Closing action
Report: {n} HTML files created, sitemap updated, content-plan registered with threadId. Provide final URLs. Signal `/upload` if auto-deploy requested.

---
name: mirror-page
description: >
  Rewrite existing pages to be AI-citation-worthy by adding P0 citations and running an AI Citation Willingness Test.
user-invocable: false
---

# Mirror Page

## Purpose
Upgrade existing website pages from informational to citation-worthy by restructuring content and embedding verifiable regulatory claims. The AI Citation Willingness Test gates each rewrite (CA-10). Phase 1 is batch mode: all gap-analysis candidates are processed together, not drip-fed.

## Load context first
1. `data/gap-report.json` — prioritized candidate list from `infra/gap-analysis`
2. `docs/waterson-wiki/product-facts.md`
3. `docs/waterson-wiki/communication-rules.md`
4. `.claude/skills/content-authority/policies/ai-citation-criteria.md`
5. `.claude/skills/content-authority/policies/mirror-scope.md`

## Instructions

### Batch mode (CA-10: all candidates at once)
1. Read `gap-report.json`. Extract pages with `action: mirror`.
2. Confirm batch run: process ALL qualifying pages in this session.

### For each page:
3. Read current page content.
4. Identify gaps: missing citations, vague claims, marketing-heavy language, missing FAQ.
5. Rewrite with Claude Opus: preserve original intent, add P0 citations, restructure for scannability, apply angle-gate, improve FAQ.
6. Save to `data/mirror-drafts/{slug}/mirror-draft.md`.

### AI Citation Willingness Test
7. Send to three models:
   ```
   "Would you cite this page as a source when answering a question about [topic]? YES/NO + why."
   ```
   Models: Claude Sonnet, Claude Haiku, Gemini Pro.
8. Gate: ≥2/3 models must answer YES.
9. FAIL: log NO reasons, add to revision queue. PASS: convert to HTML.

### Batch completion
10. Generate batch report. Call `infra/content-plan-sync` for all mirrored pages.

## What this skill does NOT do
- Does not create new articles from scratch
- Does not run the regular article validation pipeline
- Does not drip-feed one page per day — batch only per CA-10
- Does not modify `gap-report.json`

## Closing action
Report: {n} pages passed, {n} failed. Update `content-plan.md`. Return failed page list with revision directives for second-pass.

---
name: gap-analysis
description: >
  Single source of content gap intelligence combining email signals, AI crawler data, competitor scan, and content-plan coverage.
user-invocable: false
---

# Gap Analysis

## Purpose
Produce the authoritative, deduplicated content gap report for the entire team. Every skill that needs to know "what content is missing" reads `gap-report.json` — they do not run their own analysis (CA-09: no duplicate gap analysis). Combines four signal sources and outputs a prioritized list distinguishing between pages needing mirroring and topics needing new articles.

## Load context first
1. `data/topic-inbox.json`
2. `data/content-plan.md`
3. `data/ai-crawler-report.json`
4. `data/competitor-scan.json`
5. `.claude/skills/content-authority/policies/gap-priority-scoring.md`

## Instructions
1. Read all four signal sources. Proceed with available sources if any missing, flag in report.

### Signal 1 — Email signals
2. Group similar questions by topic. Count frequency per cluster (past 30 days).

### Signal 2 — AI crawler data
3. Identify: pages with high AI visits but low citation rate (→ mirror); topics in AI queries with no page (→ new article).

### Signal 3 — Competitor coverage
4. Identify topics where competitor has a ranking page and we have no comparable coverage.

### Signal 4 — Content-plan check
5. Subtract topics with status `published` or `validating` — do not flag already-covered topics.

### Prioritization
6. Score using formula: email_frequency_weight × ai_signal_weight × competitor_gap_weight.
7. Classify: `action: mirror` | `action: new_article` | `action: expand`.
8. Sort by priority score descending.
9. Write to `data/gap-report.json`.

## What this skill does NOT do
- Does not write articles or mirror pages — only identifies and prioritizes gaps
- Does not mine email topics directly — reads already-processed `topic-inbox.json`
- Does not update `content-plan.md`
- Does not scan Gmail or HubSpot

## Closing action
Write `gap-report.json`. Report: {n} total gaps, top 5 priority with action type. This is now the authoritative source for `mine-topics`, `mirror-page`, and `write-article`.

---
name: content-plan-sync
description: >
  Write to content-plan.md in unified format with mandatory source metadata, deduplication, and status tracking.
user-invocable: false
---

# Content Plan Sync

## Purpose
Maintain `content-plan.md` as the single reliable record of all content work — from initial topic proposal through published article. Every entry must carry its originating signal metadata (CA-08), enabling full traceability from published URL back to customer email.

## Load context first
1. `content-plan.md`
2. `.claude/skills/content-authority/policies/scan-contract.md`
3. `data/source-materials/{slug}/source-material.md`

## Instructions

### On every call — load and lock
1. Read `content-plan.md` in full.
2. Identify operation type: `add`, `update_status`, or `bulk_update`.

### Operation: add
3. Verify CA-08 required fields: source_type, signal_strength, source_ids (threadId), topic, status.
4. Deduplication check: if slug found with `published` → reject `DUPLICATE_PUBLISHED`. If found with other status → return `DUPLICATE_IN_PROGRESS`. If not found → proceed.
5. Append new entry to `content-plan.md`.

### Operation: update_status
6. Find entry by slug.
7. Validate legal transition: proposed → researching → drafting → validating → published.
8. Update status and `updated_at`.
9. If transitioning to `published`: also record `published_at` and `urls`.

### Operation: bulk_update
10. Process each item sequentially. Apply deduplication per item.

## Status lifecycle
proposed → researching → drafting → validating → published (revision loop may cycle)

## What this skill does NOT do
- Does not evaluate content quality or topic relevance
- Does not write articles or perform research
- Does not delete existing entries — additive and update only
- Does not resolve duplicate conflicts automatically

## Closing action
Report operation result (SUCCESS / DUPLICATE / ERROR). Confirm `content-plan.md` updated. Return final entry object.

---
name: pdca-update
description: >
  Weekly PDCA cycle: aggregate measurements, identify gaps, propose policy updates, and write learnings to team memory.
user-invocable: false
---

# PDCA Update

## Purpose
Close the improvement loop by analyzing the week's validation data against OGSM measurement targets and proposing concrete adjustments to policies and skills. All proposals require human approval before any file is modified — this skill identifies and recommends, never auto-applies.

## Load context first
1. `data/drafts/*/validation-report.json` — past 7 days
2. `data/drafts/*/persona-review.json` — past 7 days
3. `data/drafts/*/fact-check-report.json` — past 7 days
4. `data/mirror-drafts/*/citation-test-results.json`
5. `.claude/skills/content-authority/SKILL.md` — OGSM M targets
6. `.claude/skills/content-authority/memory/team-learnings.md`

## Instructions

### Step 1 — Aggregate weekly measurements
1. Collect all validation reports from past 7 days.
2. Calculate: median 3-Model eval score (target ≥8.0), fact-check first-pass rate (target >85%), persona Q7 first-attempt rate, AI citation test pass rate, revision cycle average (target ≤1.5).

### Step 2 — Identify gaps
3. Flag any metric below target. Identify pattern: one step failing? one persona always Q7=NO? specific article types scoring low?
4. Review `team-learnings.md` — do not re-propose already-tried solutions.

### Step 3 — Propose updates (NO auto-apply)
5. For each gap, draft specific proposal: which file, exact text change.
6. Format as testable hypothesis: "If we change X, metric Y improves by Z."
7. Assign effort: LOW (1 file edit) / MEDIUM (skill rewrite) / HIGH (new component).
8. All proposals listed for human review — do NOT modify any files.

### Step 4 — Write learnings to team memory
9. Append concise summary to `memory/team-learnings.md`: metrics vs targets, top patterns, proposals pending.

### Step 5 — Write PDCA report
10. Write `data/pdca/pdca-{YYYY-WW}.json`.

## What this skill does NOT do
- Does not auto-apply any changes — human approval required for all proposals
- Does not execute articles, run validation, or write content
- Does not modify claim banks or waterson-wiki
- Does not delete past learnings

## Closing action
Write `pdca-{YYYY-WW}.json`. Append summary to `team-learnings.md`. Present proposals with effort and hypothesis. Wait for approval before any file is changed.

---
name: morning-scanner
description: >
  Daily content pipeline: read Gmail Extension scan results, digest into content
  briefs, run gap analysis, update priority queue. Does NOT scan Gmail/HubSpot
  directly — consumes the shared daily-tasks.json produced by
  gmail-reply-extension's scan-classify.
model: claude-opus
schedule: "15 7 * * 1-5"
tools: ["Read", "Write", "Bash"]
---

# Morning Scanner

## Trigger
Every weekday at 7:15 AM PST (15 min after Gmail Extension's scan at 7:00 AM).

## Why 7:15, not 7:00
The Gmail Extension's daily-morning agent runs at 7:00 AM and produces
daily-tasks.json. We wait 15 minutes to ensure the scan is complete before
consuming it. This eliminates duplicate Gmail/HubSpot API calls — scan runs
once, both teams use it.

## Steps

### 1. Digest Scan Results
- Run digest-for-content.py
- Input: gmail-reply-extension/workspace/briefs/YYYY-MM-DD-daily-tasks.json
- Writes: reply-inbox.json (full copy) + topic-inbox.json (digested)
- Gate: topic-inbox.json exists and has ≥0 tasks

### 2. Gap Analysis
- Invoke [infra] gap-analysis
- Filter: only article_potential HIGH or MEDIUM
- Deduplicate: skip topics already in content-plan.md
- Output: YYYY-MM-DD-priority-queue.json

### 3. Content Plan Sync
- Invoke [infra] content-plan-sync
- Each new entry must include: source_type, threadId, hubspot_contact_id,
  customer_voice, why_this_matters
- Gate: new entries have source metadata (not just title + URL)

---
name: article-writer
description: >
  On-demand article production pipeline: research → write → validate → publish.
  Triggered when a topic is approved and ready for development.
model: claude-opus
trigger: on-demand
tools: ["Read", "Write", "Bash"]
---

# Article Writer

## Trigger
Triggered on-demand when a topic is approved in the priority queue by a human reviewer.

## Pipeline

research → write → validate → publish

### 1. Research
- Invoke composite/research-topic (Gemini Pro with search grounding)
- Input: priority-queue.json entry (slug, source-material.md already exists)
- Output: research-context.md

### 2. Write
- Invoke composite/write-article (Claude Opus)
- Gate: claim-bank.json must exist with ≥3 P0 claims before writing (CA-06)
- Output: data/drafts/{slug}/draft.md

### 3. Validate
- Invoke composite/validate-article (orchestrates fact-check + persona-review + 3-Model eval)
- Budget: 2 hours, no round limit (iterate until median ≥8.0)
- If validation fails, loops back to write-article with revision instructions

### 4. Publish
- Invoke composite/publish-article (Python HTML assembly — 0 AI tokens)
- Registers in content-plan.md with threadId (CA-08)
- Updates sitemap.xml (EN + ZH + AEO URLs)
- Does NOT push to Git — signal /upload skill for deploy

---
name: page-mirror
description: >
  Batch-rewrite existing pages to AI-citation-worthy format. Phase 1: batch all,
  Phase 2: ongoing maintenance as new pages are added.
model: claude-opus
trigger: phase-1-batch + phase-2-ongoing
tools: ["Read", "Write", "Bash"]
---

# Page Mirror

## Trigger
- Phase 1: one-time batch triggered manually — rewrite ALL existing pages
- Phase 2: triggered when new pages are added to the site

## Strategy: Phase 1 = batch-rewrite ALL (not drip-feed)
CA-10 blocking rule: never drip-feed one page per day.
Batch ALL gap-analysis candidates in a single session.

## Pipeline

gap-analysis → mirror → test → publish

### 1. Gap Analysis
- Invoke [infra] gap-analysis
- Filter: pages with action: mirror (existing pages that are not citation-worthy)
- Output: gap-report.json with prioritized page list

### 2. Mirror
- Invoke composite/mirror-page (Claude Opus rewrite to AI-citable format)
- For each page: add P0 citations, restructure for scannability, apply angle-gate
- Output: data/mirror-drafts/{slug}/mirror-draft.md

### 3. AI Citation Willingness Test (quality gate)
- Ask 3 AI models: "Would you cite this page as a source for [topic]?"
  Models: Claude Sonnet + Claude Haiku + Gemini Pro
- Gate: ≥2/3 models must answer YES
- If FAIL: log NO reasons, add to revision queue, continue to next page

### 4. Publish
- Pages that pass citation test: convert via md-to-html.py (0 AI tokens)
- Update sitemap.xml
- Register in content-plan.md via infra/content-plan-sync

## Phase 2 — Ongoing maintenance
After Phase 1 completes, this agent runs whenever new pages are added.
Same pipeline, single-page mode instead of batch mode.

# Scan Contract — daily-tasks.json Schema

## Source
Produced by: gmail-reply-extension/skills/composite/scan-classify
Consumed by: content-authority/scripts/digest-for-content.py
Location: gmail-reply-extension/workspace/briefs/YYYY-MM-DD-daily-tasks.json

## Required Fields

| Field             | Type   | Used by                                |
|-------------------|--------|----------------------------------------|
| task_id           | string | Both teams — unique identifier         |
| thread_id         | string | Content team — trace to original email |
| sender_email      | string | Content team — customer identification |
| subject           | string | Content team — topic extraction         |
| body_preview      | string | Content team — customer voice           |
| customer          | string | Both teams — display name              |
| company           | string | Content team — context                 |
| source            | string | Content team — email vs call vs form   |
| hubspot_contact_id| string | Content team — CRM linkage             |
| priority          | string | Both teams — triage                    |
| persona           | string | Both teams — audience targeting        |

## Rules
1. Additive only: new fields can be added. Existing fields cannot be renamed
   or removed.
2. Type stability: a field's type must not change.
3. body_preview minimum: must contain ≥100 characters of original content.
4. thread_id required: every task must have a thread_id. If no Gmail thread,
   use HubSpot object ID prefixed with hs_.

## Breaking Change Protocol
1. Add the new field alongside the old one (parallel run)
2. Update both consuming teams to read the new field
3. Remove the old field only after both teams confirm

# Knowledge Priority — Source Hierarchy

## Priority Tiers

| Tier | Sources | Use |
|------|---------|-----|
| P0 | NFPA / ADA / ANSI / IBC / UL | Regulatory authority — ONLY these for code citations in articles |
| P1 | Waterson Wiki (internal ground truth) | Product facts, specs, approved phrasings |
| P2 | Industry publications (Door & Hardware Federation, BHMA journals) | Background and industry context |
| P3 | Competitor data (competitor websites, specs) | Market context, objective comparison only |
| P4 | General web (blogs, forums, unverified sources) | Background only — never cite directly |

## Rules

1. **P0 only for regulatory citations**: Any claim citing a building code, fire code, accessibility standard, or safety standard MUST trace to a P0 source with a specific section reference (e.g., NFPA 80 Section 4.1.2 — not just "per NFPA 80").

2. **P1 for product facts**: All Waterson product specifications, certifications, and capabilities must trace to Wiki, not to marketing copy.

3. **P2-P4 are background only**: They inform writing context and competitor gap analysis. They cannot be cited as authoritative in published articles.

4. **Never mix tiers in citation**: Do not cite a P2 source for a code requirement that should come from P0. The reader — an architect or facility manager — will verify claims against P0 originals.

## Why this matters
Architects and facility managers need to trust that every regulatory claim in our content can survive independent verification against the primary standard. P0 citations = citation-worthy. P4 citations = the reason AI models don't cite our pages.

# Source Preservation Policy

## Rule
Every article must trace to ≥1 real customer question.

## Required for every article
1. **Email raw content preserved verbatim** in `data/source-materials/{slug}/source-material.md`
2. **Gmail threadId** recorded in source-material.md metadata
3. **Never paraphrase customer words** in source extraction — copy verbatim only

## What "verbatim" means
Copy the customer's exact words, including grammatical errors, technical misunderstandings, and informal language. These imperfections are signal — they reveal exactly what the customer is confused about and what vocabulary they use to search.

## What "preserved" means
The raw content must remain readable in source-material.md after the article is published. It is not a temporary staging file — it is a permanent record that can be audited to verify the article's origin signal.

## Why this rule exists (CA-01 and CA-02)
- CA-01: Writing from AI-brainstormed topics produces content that sounds good but answers questions nobody is actually asking. Customer emails are demand-validated topics.
- CA-02: Paraphrased customer quotes lose the authentic signal. The exact words matter for tone calibration and keyword alignment with how customers actually search.

## Anti-pattern
NOT: "A customer asked about fire door gap requirements."
INSTEAD: preserve verbatim — "I have a fire door that has about a 1/4 inch gap at the top — does NFPA 80 specify a max gap or is it AHJ-dependent?"

## Scope
This policy applies to: email topics, HubSpot conversation topics, and any customer interaction used as an article origin signal. It does not apply to gap-analysis topics derived from AI crawler data (no customer quote exists).

# Model Routing Policy

## Routing Table

| Task | Model | Why |
|------|-------|-----|
| Research, fact verification | Gemini Pro (gemini-2.5-pro) | Search grounding — real-time regulatory data |
| Writing, strategy | Claude Opus | Highest language quality for professional audience |
| Structured output, validation | Codex | Best at JSON output, schema-conformant responses |
| Claim bank, HTML, sitemap, validators | Python scripts | 0 tokens — deterministic, no AI drift |
| 3-family blind eval | Sonnet + Haiku + Gemini | Different families prevent self-grade bias (CA-04) |

## Rules

1. **Never use Claude for research** — Claude's training data has a knowledge cutoff. Gemini Pro with search grounding provides current regulatory information.

2. **Never use Gemini for writing** — writing quality matters for our professional audience (architects, facility managers). Claude Opus produces more nuanced, authoritative prose.

3. **Never use the same model to write AND evaluate** — self-grading is systematically biased. The 3-Model blind eval uses Sonnet, Haiku, and Gemini (CA-04). None of these wrote the article.

4. **Never use AI for deterministic tasks** — claim bank building, citation validation, HTML conversion, and sitemap updates are deterministic operations. Running them through AI wastes tokens and introduces hallucination risk (CA-05).

5. **CLI subscriptions only** — use `gemini` CLI (Google AI Ultra) and `codex` CLI ($200/mo subscriptions). Never use REST APIs with quota-limited keys.

## Why model routing matters
Each model has different strengths. Routing tasks to the wrong model produces worse output AND costs more tokens. The routing table is optimized for the specific demands of regulatory content: accuracy (Gemini research), authority (Opus writing), and unbiased evaluation (3-family blind eval).

# Quality Gate Policy

## Four mandatory gates before publication

### Gate 1 — Claim Bank (CA-06)
- `build_claim_bank.py` must run and exit 0
- P0 claim count must be ≥3
- Failure blocks: `composite/write-article` cannot start without passing Gate 1

### Gate 2 — 3-Model Blind Evaluation (CA-04)
- Three models from different families: Claude Sonnet + Claude Haiku + Gemini Pro
- Each model scores the draft independently (no model sees others' scores)
- Median score must be ≥8.0 out of 10
- Budget: 2-hour window, no round limit — iterate until median ≥8.0 or escalate
- Failure routes back to `composite/write-article` with revision instructions

### Gate 3 — 3 Persona Q7 = YES (CA-07)
- Architect, Facility Manager, Contractor — each must answer Q7=YES
- Q7: "Would you bookmark this page or share it with a colleague?"
- Any Q7=NO is a hard block — article must be revised
- Q5 angle-gate: reader must feel "helped" not "sold to"

### Gate 4 — 3 Python Validators exit 0 (CA-05)
- `validate_citations.py` — all P0 claims exist in claim-bank.json
- `validate_specs.py` — no product specs contradict waterson-wiki
- `validate_corrections.py` — no repeat of known errors in corrections-log.md
- Any non-zero exit = automatic CRITICAL failure

### AI Citation Willingness Test (page-mirror only)
- Ask 3 AI models: "Would you cite this as a source?"
- Gate: ≥2/3 models say YES
- This gate applies to mirror-page rewrites — not to new articles (which use Gates 1-4)

## Why these specific gates
Each gate catches a different failure mode: Gate 1 = no regulatory authority; Gate 2 = poor quality writing; Gate 3 = wrong audience/tone; Gate 4 = factual errors. Running all four gates in sequence filters articles that look good on the surface but fail the actual test — whether an AI engine would trust them enough to cite.

# Angle Gate Policy

## Core rule
Every article must make the reader feel **helped**, not **criticized** or **sold to**.

## What this means in practice

### Positive framing — present solutions, not problems
NOT: "Many contractors make the mistake of installing hinges incorrectly."
INSTEAD: "Here is the installation sequence that ensures NFPA 80 compliance."

### No disparagement
NOT: "Unlike Brand X, which only meets minimum requirements, Waterson exceeds..."
INSTEAD: "NFPA 80 sets the minimum. Waterson [specific spec] provides [specific benefit for specific use case]."

### Waterson as contextual example, not centerpiece
- Include Waterson self-closing hinge as a contextual example where the product is genuinely relevant
- It must not be the centerpiece of every article
- Readers are architects and facility managers — they can tell when content is product promotion disguised as information

### The Q5 test (persona-review)
Persona simulations answer Q5: "Does this feel like it's helping you or selling to you?"
- Acceptable answers: "helping" or "mostly helping"
- Unacceptable: "selling" — triggers a WARNING even if Q7=YES
- If 2+ personas answer "selling": treat as soft FAIL, require revision before proceeding

## Why the angle-gate exists
AI citation engines (GPT, Gemini, Perplexity) are trained to prioritize authoritative, neutral sources. Marketing-angled content is recognized and deprioritized. The angle-gate enforces the writing posture that makes our content citation-worthy — not just readable.

## Enforcement
- `composite/write-article`: checks angle per paragraph during drafting
- `core/fact-check`: Gemini Pro flags communication-rules violations (Phase 2)
- `core/persona-review`: Q5 is a formal angle measurement gate

# Content Authority — Mandatory Rules

## BLOCKING Rules

| Rule  | MUST NOT                                               | MUST INSTEAD                                               |
|-------|--------------------------------------------------------|------------------------------------------------------------|
| CA-01 | Write articles from AI-brainstormed topics             | Every article traces to ≥1 real customer question (threadId) |
| CA-02 | Discard email raw content after topic extraction       | Preserve original words + threadId in source-material.md   |
| CA-03 | Use non-P0 sources as regulatory authority             | Only NFPA/ADA/ANSI/IBC/UL for code citations               |
| CA-04 | Same model writes and evaluates (self-grading)         | 3-Model blind eval from different families                  |
| CA-05 | Use AI for deterministic tasks                         | Python scripts for claim bank, validators, HTML, sitemap    |
| CA-06 | Skip claim bank before writing                         | build_claim_bank.py MUST run first (Gate 1)                 |
| CA-07 | Publish without 3 Persona Q7=YES                       | Architect + FM + Contractor all say YES                     |
| CA-08 | Add to content-plan without source metadata            | Must include source_type, signal_strength, source_ids       |
| CA-09 | Run gap analysis in multiple places                    | Single gap-analysis infra skill, consumed by all depts      |
| CA-10 | Drip-feed page rewrites monthly                        | Phase 1: batch-rewrite ALL pages in 2 weeks                 |

## Model Routing

| Task                    | Model          | Why                         |
|-------------------------|----------------|-----------------------------|
| Research, fact check    | Gemini Pro     | Search grounding            |
| Writing, strategy       | Claude Opus    | Highest language quality    |
| Structure, validation   | Codex          | Best at structured output   |
| Claim bank, HTML, sitemap| Python script  | 0 tokens, deterministic     |
| Blind eval              | Sonnet+Haiku+Gemini | Different families     |

# Anti-patterns

NOT: Write articles from AI-brainstormed topics without customer demand signal
INSTEAD: Every article traces to ≥1 real customer question (threadId in source-material.md)

NOT: Discard email raw content after topic extraction
INSTEAD: Preserve customer's original words + threadId in source-material.md

NOT: Use non-P0 sources as regulatory authority
INSTEAD: Only NFPA/ADA/ANSI/IBC/UL for code citations. P2-P4 = background only

NOT: Same AI model writes and evaluates (self-grading)
INSTEAD: 3-Model blind eval from different families

NOT: Use AI for deterministic tasks
INSTEAD: Python scripts for claim bank, validators, HTML, sitemap (0 tokens)

NOT: Drip-feed page rewrites monthly
INSTEAD: Phase 1 batch-rewrite ALL pages, Phase 2 maintain standard

NOT: Evaluate content with human metrics only
INSTEAD: AI Citation Willingness Test (ask AI "would you cite this?")

NOT: Run gap analysis in multiple places
INSTEAD: Single gap-analysis infra skill

NOT: Add to content-plan without source metadata
INSTEAD: Must include source_type, threadId, signal_strength

NOT: Skip claim bank before writing
INSTEAD: build_claim_bank.py MUST run first (Gate 1)

NOT: Give each agent its own OGSM
INSTEAD: 1 team OGSM, agents are lightweight schedulers with trigger + steps only