/peec-checkup

name: peec-checkup
description: Read-only health check for an existing Peec AI project. In one pass produces (1) a setup-quality audit (red flags from the structural setup — wrong competitors, funnel gaps, taxonomy issues), (2) a brand-performance snapshot (visibility per stage / engine, hero prompts winning vs losing, source diversity, competitor delta), and (3) a priority-ranked list of 5–8 concrete improvements drawn from Peec's get_actions + URL gap data. Works from day 1 of Peec data — no 4-week history needed. Never writes to Peec or to setup_state.json. Use when the user asks "Wo stehe ich?", "Wie ist mein Status?", "Was sind die Verbesserungspotenziale?", "Mein Setup checken", or runs /peec-checkup.
user-invocable: true

Peec Checkup

Role

Single read-only pass over a Peec project that answers three questions:

1. **Setup quality** — is the project configured correctly, or are there structural problems holding back every measurement? 2. **Brand performance now** — where does the brand actually stand, snapshot today? 3. **Top improvements** — which 5–8 concrete moves would move the needle most, ranked?

No writes. No content production. No outreach. Pure diagnosis + recommendations.

Input

• `project_id` — Peec project (read from `setup_state.json` per pre-flight; fallback to `mcp__peec-ai__list_projects` if state missing)
• optional `date_range` — default last 28 days (falls back to whatever data exists if project is younger)
• optional `top_n` — number of improvements to surface, default 5, max 8

Output

One markdown report saved to `<project>/checkups/YYYY-MM-DD_checkup.md` (schema in §6). Mirrored to stdout for the user. Never modifies setup_state.json or any Peec data.

When to use

• "Wo stehe ich bei Peec?" / "Wie ist mein Status?"
• "Mein Setup checken" / "Was läuft falsch bei meinem Peec-Projekt?"
• "Welche Verbesserungspotenziale gibt es?"
• Onboarding a project from another consultant — first pass to see what was set up
• Periodic ritual: monthly without 4 weeks of action history (use `peec-report` instead when history exists)
• After someone else changed the Peec project and you want to see what shifted

Do not use when:

• The user wants ONE next action — that is `/peec-agent`
• The user wants attribution of past actions — that is `/peec-report`
• The project is empty — that is `/peec-setup` (full mode)
• The user wants to mutate Peec — every other skill, not this one

---

Pipeline

0. Pre-flight — setup state required (lenient)

Per [`_shared/SETUP_STATE.md`](../_shared/SETUP_STATE.md), this skill prefers a state file but **does not hard-stop** without one — checkup is itself the audit you'd run when state is missing. Logic:

Read <project>/growth_loop/setup_state.json
If present:
  Use peec_project_id, target_country, prompt_language from state.
  Note the setup age in the report.
If missing:
  Resolve project via mcp__peec-ai__list_projects.
  Note in the report: "no setup_state.json — run /peec-setup
  (mode: import) after this checkup to persist findings."
  Default target_country=DE, prompt_language=de UNLESS the user said otherwise.

This is the only consumer skill allowed to run without a state file — because its whole job is to tell you whether you should run `peec-setup` next.

1. Setup-quality audit (read-only mirror of peec-setup Phase 1 + 2)

Parallel reads:

mcp__peec-ai__list_brands(project_id)
mcp__peec-ai__list_prompts(project_id, limit=200)
mcp__peec-ai__list_topics(project_id)
mcp__peec-ai__list_tags(project_id)

Score against this checklist (each item = +/− points; record per-finding evidence):

| Check | Red flag | |---|---| | Competitors are real buyer alternatives | SaaS tool brands present (SEMrush, Ahrefs, Sistrix, Moz, Ryte, Yoast, Frase, Surfer, ScreamingFrog) — distort SoV | | Competitors include AI-recommended ones | Compare list to brands appearing in `list_chats` sources but not tracked → "invisible competitors" | | Funnel coverage balanced | Counts per stage (Awareness/Consideration/Decision/Retention) — flag any stage <20% or >50% of total | | Prompts use buyer language | Quick scan: ≥3 prompts contain platform-vendor phrases ("empfiehl", "vergleich", "alternativ") | | Prompts under 200 chars | Peec hard limit — list any over | | Topics enable funnel slicing | Topics named after funnel stages OR by clear analytical axis (offer, audience). Flag topics that are pure themes ("AI", "SEO") with no slicing value | | Tags are richer than the default 4 | If only `branded`/`non-branded`/`informational`/`transactional` exist → no offer/persona slicing possible | | Brand aliases handle Umlauts | Any brand with Umlauts in name but no ASCII alias (`"Stürkat"` without `"Stuerkat"` alias) → matching fails on chats | | Hero prompt identified | `setup_state.hero_prompt_id` set OR clearly inferrable from get_brand_report; flag if not |

Output: a **Setup Health Score** = % of checks passing, plus the bulleted findings (severity P0/P1/P2).

2. Brand-performance snapshot (read-only mirror of Phase 9)

own_brand_id = first brand whose domain matches setup_state.domain
              (or whose name == own_domain root); if ambiguous, ASK once

# Per-stage visibility
mcp__peec-ai__get_brand_report(
  project_id, start_date, end_date,
  dimensions=["topic_id"],
  filters=[{field: "brand_id", operator: "in", values: [own_brand_id]}]
)

# Per-engine visibility
mcp__peec-ai__get_brand_report(
  project_id, start_date, end_date,
  dimensions=["model_id"],
  filters=[{field: "brand_id", operator: "in", values: [own_brand_id]}]
)

# Per-prompt — find winners + losers
mcp__peec-ai__get_brand_report(
  project_id, start_date, end_date,
  dimensions=["prompt_id"],
  filters=[{field: "brand_id", operator: "in", values: [own_brand_id]}]
)

# Source diversity (how many distinct sources is the brand cited from)
mcp__peec-ai__get_url_report(
  project_id, start_date, end_date,
  dimensions=["url"],
  filters=[{field: "br