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, 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):

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: "brand_id", operator: "in", values: [own_brand_id]}],
  limit=50
)

# Competitor delta — strongest opposition per topic
mcp__peec-ai__get_brand_report(
  project_id, start_date, end_date,
  dimensions=["topic_id", "brand_id"]
)

Compute:

• Visibility now — overall % + per stage + per engine
• Hero prompts winning — prompts where own_brand visibility > 50% (top 5)
• Hero prompts losing — prompts where own_brand visibility = 0 AND a competitor visibility > 30% (top 5)
• Funnel weakness — the stage with the lowest visibility (and which competitor dominates it)
• Engine weakness — the engine where the brand is invisible (chatgpt vs perplexity vs google-ai-overview)
• Source diversity — count of distinct domains the brand is cited from; <5 = weak; >15 = healthy

If the project has < 7 days of data: explicitly say so and skip the per-prompt sections — only report counts. Do not invent insights from one day of data.

3. Improvement candidates (raw inputs)

mcp__peec-ai__get_actions(project_id, scope="overview",  start_date, end_date, limit=10)
mcp__peec-ai__get_actions(project_id, scope="editorial", start_date, end_date, limit=10)
mcp__peec-ai__get_actions(project_id, scope="ugc",       start_date, end_date, limit=10)
mcp__peec-ai__get_actions(project_id, scope="owned",     start_date, end_date, limit=10)

# Where competitors get cited but I don't
mcp__peec-ai__get_url_report(
  project_id, start_date, end_date,
  filters=[{field: "gap", operator: "gt", value: 0}],
  limit=25
)

This produces a raw candidate pool of ~50 items. Do not return all of them.

4. Prioritise — score and rank

For each candidate, compute a leverage score:

leverage = impact × actionability × strategic_fit

Multiplicative — anything with a 0 in any dimension is dropped (those are noise).

Take top top_n (default 5). For each, output:

• One-sentence action
• Which signal in §1 / §2 caused it (causal trace, not just "Peec said so")
• Suggested handoff skill (/peec-content-intel, /peec-outreach, /peec-setup partial:<phase>)
• Estimated effort (S/M/L)
• Estimated 4-week metric impact (visibility delta on which prompt or zone)

Always include at least one structural improvement (from §1) if the Setup Health Score is < 80%. Don't drown setup issues under content opportunities — broken setup invalidates everything else.

5. Synthesize report

Save to <project>/checkups/YYYY-MM-DD_checkup.md (create dir if missing) and stream to user. See §6 schema.

End with one decisive sentence: "Empfohlene nächste Aktion: <skill>" — the single most leveraged item from §4.

6. Output schema

# Peec Checkup — <domain> · <YYYY-MM-DD>

## TL;DR
- Visibility now: **<X%>** (was <prev>% N days ago — only if prior checkup exists)
- Setup health: **<Y%>** (<P0 count> P0 issues, <P1 count> P1)
- Strongest funnel: <stage> (<X%>) · Weakest: <stage> (<Y%>)
- Top competitor on weak stage: <brand>
- Recommended next action: <one skill + scope>

## 0. Inventory (counts as of <date>)

| Bucket | Count | Notes |
|---|---|---|
| Brands tracked | <N> | own=1 · competitors=<N-1> · invisible candidates=<N> |
| Prompts total | <M> | active=<M_active> · paused=<M_paused> |
| · Awareness | <a> | <a/M %> |
| · Consideration | <b> | <b/M %> |
| · Decision | <c> | <c/M %> |
| · Retention | <d> | <d/M %> |
| · Unclassified | <e> | flag if >0 — funnel-stage missing |
| Topics | <T> | named: <list first 5> |
| Tags | <G> | non-default: <list non-default tags> |
| Chats analysed in window | <C> | per engine: chatgpt=<x> · perplexity=<y> · gao=<z> |
| Window | <date_range> | days_with_data=<N> |

If `days_with_data < 7` → mark sections 2 + 3 with **"insufficient data"** badge and skip per-prompt detail.

## 1. Setup health (<Y%>)

### P0 — must fix (block valid measurement)
- <finding> — evidence: <data point>

### P1 — should fix (skews insights)
- <finding> — evidence: <data point>

### P2 — nice to have
- <finding>

## 2. Brand performance now (window: <date_range>)

### Visibility per funnel stage
| Stage | Visibility | Top competitor (delta) |
|---|---|---|
| Awareness | X% | comp.de (-Y%) |
| Consideration | … | … |
| Decision | … | … |
| Retention | … | … |

### Visibility per engine
| Engine | Visibility |
|---|---|
| chatgpt-scraper | X% |
| perplexity-scraper | … |
| google-ai-overview-scraper | … |

### Hero prompts — winning (top 5)
1. **<prompt text>** — Y% visibility, mostly via <engine> · sources: <count distinct>

### Hero prompts — losing (top 5)
1. **<prompt text>** — 0% visibility · top competitor: <brand> at <Z%> · cited URL type: <LISTICLE/ARTICLE/COMPARISON/HOW_TO_GUIDE/DISCUSSION>

### Source diversity
<N> distinct source URLs · top sources: <list 5> · health: <weak / OK / healthy>

## 3. Top <N> improvements (priority-ranked)

### #1 — <short action title>
- **Why now:** <causal trace from §1 or §2>
- **Handoff:** <skill + parameters>
- **Effort:** <S / M / L>
- **4-week metric:** <specific delta>

### #2 …

## Recommended next action
**<one skill invocation>** — because <one sentence>.

---
*Read-only checkup. No Peec data was modified. State file: <found at path | missing>.*

Guardrails

• *Never call `mcp__peec-ai__create_ or delete_` or `update_`.** Pure read.
• Never write `setup_state.json`. Only peec-setup writes it. If state was missing, the report tells the user to run /peec-setup partial:import to persist findings.
• Never invent insights from < 7 days of data. Say "insufficient data" explicitly.
• Never silently assume language/country. If state has them, use them. If not, ask once before §3.
• Never bury setup issues under content opportunities. A Setup Health Score < 80% means the structural fix outranks any content recommendation in §4.
• Never produce >8 improvements. If 50 candidates score similarly, the scoring is wrong — re-tighten thresholds, don't widen output.

Relationship to other skills

/peec-checkup
   │ (read-only diagnosis)
   ↓
   reports → user decides
   │
   ├── if structural P0 → /peec-setup (partial / audit)
   ├── if specific prompt to win → /peec-content-intel
   ├── if outreach gaps → /peec-outreach
   ├── if you want ONE decisive next move → /peec-agent
   └── if you want time-series + attribution → /peec-report (needs 4+ weeks)

/peec-start may route to /peec-checkup when the user's intent is observational ("how am I doing?") rather than action-driven ("what should I do?"). The two are complementary, not redundant: checkup is the lens, growth-agent is the trigger.