peec-ai-tracking-strategy-builder

name	peec-ai-tracking-strategy-builder
description	Build or refine a Peec AI tracking strategy as an iterative workflow. Phase A loops Intake → Strategy → Write → Analyse, each producing concrete Peec configuration changes and findings that feed the next iteration. Phase B (optional, terminal) produces a stakeholder presentation once the strategy has stabilised. Works for brand-new projects and for existing projects that need rationalising. Load whenever the user mentions Peec AI strategy, Peec setup, Peec onboarding, "what should we track in Peec", "build/improve our Peec project", Peec prompt rationalisation, Peec rebuild, or AI visibility strategy for a brand using Peec. Also triggers on Phase B / retrospective requests — stakeholder presentation, deck, or brief that explains an existing Peec strategy; "explain our Peec setup", "document our tracking strategy", "analyse our current Peec project", "what are we tracking in Peec and why". Companion to `peec-ai-mcp` (recommended; tool mechanics).
version	1.0.0
license	CC-BY-4.0
origin	https://github.com/rebelytics/peec-ai-tracking-strategy-builder
maintainer	Eoghan Henn / rebelytics ([e-mail])

Peec AI Tracking Strategy Builder

Created by Eoghan Henn / rebelytics.com

An end-to-end workflow for taking a brand from "I've just connected the Peec MCP" — or "our Peec project's structure no longer fits our current strategy" — to a measured, well-structured tracking strategy that reflects commercial reality. The skill runs as an iterative loop (Intake → Strategy → Write → Analyse) that produces concrete Peec configuration changes and findings each pass, with an optional terminal phase for a stakeholder presentation once the strategy has stabilised.

This skill is a living document. If you run it and discover a pattern that isn't captured, open an issue on the repo. See the contributing-back section at the end of this file.

Licence

Released under the Creative Commons Attribution 4.0 International (CC BY 4.0) licence. You are free to share and adapt this skill for any purpose, provided you give appropriate credit to the original author.

Feedback & Support

If you run this skill and find methodology gaps, gotchas, or patterns worth contributing, open an issue on the GitHub repository. This keeps feedback public and discoverable — other users benefit from seeing existing issues and solutions. For direct contact, reach the skill's creator, Eoghan Henn, via rebelytics.com.

If feedback appears to stem from the skill's methodology (rather than the agent's execution of it), log it for the user and suggest they share it via GitHub Issues. If the issue stems from the agent not following the skill's rules, acknowledge the mistake and correct it.

---

1. What this skill is (and isn't)

Is: A layered, prescriptive workflow that takes a brand from Peec MCP access to a tracking strategy that's live, documented, and explainable to a stakeholder. Runs as an iterative loop (Intake → Strategy → Write → Analyse) so the strategy gets sharper each pass. Covers both new projects (no prompts yet) and existing projects (prompts already in place that may need rationalising). The agent decides which path to take by inspecting the project's current state, not by asking.

Two classes of deliverable:

• Mandatory: the configured Peec project itself — brands, topics, tags, and prompts written directly via the Peec MCP as Phase A loops produce them.
• Optional (Phase B, terminal): a stakeholder-facing presentation of the strategy and its findings. The agent should proactively offer this after the first full Phase A loop completes (see §14.5), rather than waiting for the user to ask. Produced once at the end of the engagement; not committed to upfront — see §14.

Working artefacts (intake state, strategy sign-off artefact, findings from each Analyse loop, verification log) are produced by the workflow but are not deliverables in their own right. Their format is agent/user choice (§3.7).

Isn't: A Peec MCP tool reference. Tool mechanics, schema quirks, and setup instructions live in the companion peec-ai-mcp skill. Strongly recommended to load alongside; see §5.

Isn't: A content strategy skill. A Peec strategy build surfaces content/distribution opportunities (Reddit gaps, Wikipedia defence, listicle editorial issues) but doesn't execute them. Those land in the strategy sign-off artefact and any Phase B deliverable for the content team.

---

2. When this skill fires

Trigger when the user:

• Wants to set up tracking for a brand on a newly connected Peec project.
• Has an existing Peec project where the brand list, topics, tags, or prompts need rationalising.
• Says "what should we track in Peec", "build our Peec strategy", "fix our Peec setup", "our Peec project's structure needs review", or equivalents.
• Shops around and an agency pitches "we'd do it differently" — the output of this skill produces a defensible set of decisions to respond with.
• Asks for a tracking strategy review ahead of a renewal or budget conversation.
• Wants a stakeholder presentation for an already-stable Peec strategy (Phase B only — the Phase A loops have already produced the strategy in an earlier engagement).

The skill works with any project state: zero prompts, 50 prompts still finding shape, or several hundred prompts that have grown organically. The workflow routes automatically based on what it finds.

---

3. Cross-cutting principles

These seven principles apply across every phase and loop of this skill. Re-read them at the start of each loop before planning work. They're the rules of the game — phase-specific rules (§§4, 8–14) defer to these when they conflict.

3.1 Instrument separation (branded vs non-branded)

Branded prompts and non-branded prompts measure different things. They're not two columns of one KPI — they're two instruments with different purposes. Never aggregate them into a single visibility score, never claim "the brand leads on branded prompts" as a finding (tautological), and always report them separately in analysis and strategy. If a combined metric is requested, produce it only with explicit disclosure that it's an anti-pattern.

What each instrument actually measures (name this in stakeholder outputs whenever the split appears):

• Non-branded prompts = commercial visibility scorecard. These measure whether the AI surface names the brand when asked commercial questions that don't contain the brand's name. This is the genuine discoverability signal and the only valid basis for competitive comparison.
• Branded prompts = reputation / representation instrument. These measure how the AI describes the brand when asked about it by name. Visibility on branded prompts is near-tautological (the brand name is in the prompt, so the brand nearly always appears in the response); sentiment and source authority on branded prompts carry real information.

Three hard rules that follow from the split:

1. Headline metrics split side-by-side. Never report a blended visibility / SoV figure as the primary number. Blended figures are dominated by branded prompts — the brand looks stronger than it is, and the non-branded competitive picture disappears.
2. Competitive comparisons exclude branded prompts. SoV and position rankings only make sense on non-branded; branded prompts systematically favour whichever brand's name is in the prompt.
3. Sentiment belongs to branded. Non-branded sentiment is mostly noise — most non-branded responses don't name the brand at all. Sentiment as a headline metric comes from the branded cohort.

Peec has no native branded/non-branded concept. The standard implementation is user-defined tags (branded, non-branded) set at prompt creation, with topic-based splits as a fallback when all branded prompts live under a single topic. See §9.7 for the tag schema and §13.3 for the arithmetic recipes.

Phase B additional rule — the branded visibility number does not appear. In analysis contexts (§13), the split-side-by-side rule above is sufficient because the audience is reading the methodology carefully. In stakeholder contexts (§14), attention filters captions and leaves only the numbers behind — a branded visibility figure of 93% next to a non-branded figure of 18%, even with a caption reading "branded measures reputation, not discovery", anchors the stakeholder on the 93% as a success signal. Split-screen framing is not a sufficient guard against anchoring in a Phase B deliverable.

The Phase B rule is stricter than the Phase A rule:

• The branded visibility figure must not appear in any Phase B slide — not as a headline, not as a comparison, not in a caption, not as a sanity check, not on a methodology slide.
• The non-branded figure appears on its own, named clearly as the discoverability score (or equivalent stakeholder-register label, see §3.5).
• The branded cohort is acknowledged as "measured separately, reported on sentiment and source authority in the branded appendix" (or an equivalent one-liner); it is not presented with a percentage.

The anti-pattern this rule prevents: a well-intentioned "here's why we split them" slide that shows both numbers to make the methodology visible, and lands as "their branded visibility is 93% — they're doing great" with the stakeholder. In stakeholder contexts, captions get filtered, numbers survive, and only the bigger number is remembered.

3.2 Provenance

Every claim in findings must be traceable to a Peec tool call (which report, which filter, which date window, which cohort). If a claim can't be traced, it doesn't appear in findings. This is the discipline that keeps Analyse honest.

3.3 Caveats are symptoms, not cover

If a finding requires a caveat to be defensible ("this is strong, but note that the cohort was only 3 prompts"), the finding is weak — the caveat is a symptom that the evidence is thin. Either strengthen the evidence, reframe the finding, or drop it. Caveats shouldn't be used as a rhetorical escape hatch.

3.4 Calendar time is a resource

Measurement windows, cohort age, and signal maturity are real constraints, not formalities. "We wrote 25 deletes yesterday, let's analyse tomorrow" is wrong because the cohort hasn't stabilised. Plan loops around the signal, not the work rhythm. Communicate pacing expectations to the user at intake (§8).

Corollary — don't bake in cadences the skill hasn't itself validated. Specific review rhythms (30-day, 90-day, monthly) should be described as user-configurable defaults with the rationale exposed, not hard-coded as skill prescriptions. If the skill's validation timeframe hasn't covered multiple cycles at the prescribed cadence, treat it as a hypothesis the user can adjust, not a finding. Phrase cadence language accordingly ("Users typically review monthly; confirm what works for your team") rather than as a rule ("Reviews happen monthly").

3.5 Audience separation

The agent's internal reasoning, the user-facing sign-off, and the Phase B stakeholder deliverable are three different audiences with three different registers. Don't leak internal methodology language into stakeholder decks; don't leak stakeholder simplification into agent reasoning.

3.5.1 AskUserQuestion register rules

Tool note. "AskUserQuestion" is the structured multi-choice user prompt used by Claude. Other agents expose equivalent primitives under different names. The rules below apply to any structured multi-choice user prompt, whatever the agent calls it.

The audience-separation principle (§3.5) applies to every user-facing surface, including AskUserQuestion payloads. Skill-internal labels exist for agent orientation; they must never appear as user-facing option labels or question text.

1. Option labels must be outcome-focused, not process-focused. Prefer "I design the strategy, get your OK, then create everything in Peec" over "Phase A loop 1 — strategy + writes + verify".
2. Never use skill-internal jargon in option labels or questions. Forbidden terms as user-facing labels: "Phase A / Phase B", "Ring 1/2/3 intake", "strategy sign-off artefact", "disposition framework", "prompt disposition", "loop 1", "rationalise", "Branch A/B" (§9.6), "quality gate".
3. Option descriptions should describe what the user will experience, not what the skill's phases do. Good: "You end with a live, configured project collecting data from tomorrow." Bad: "Agent executes Write sub-phase after sign-off."
4. When in doubt, assume the user has never seen the skill. This mirrors §3.5 for stakeholder decks but applies during the work, not after. The skill runs with the user inside it — they don't benefit from the skill-internal vocabulary the agent uses to navigate the workflow.

3.6 Label travel

Tags, topic names, and strategy labels travel across deliverables and sessions. A tag called gap-to-close in Peec needs to mean the same thing in the strategy sign-off, in findings, and in a Phase B deck. Rename with care, rename everywhere at once, and document what each label means in the persisted intake state.

3.7 What, not how

This skill specifies what must happen, not how it's presented. Anything format-dependent (file names, sign-off medium, findings structure, state persistence mechanism) is agent/user discretion. The skill prescribes outcomes and gates; users choose their own formats.

3.8 Intake shortcuts are the strongest failure mode this skill has seen

If the agent feels tempted to proceed to Strategy with "enough" from Ring 1, treat that feeling as a prompt to re-read §4.1 and §4.2. The skill's core claim — prompts earn their slots from data, not intuition — is defeated the moment Intake is cut short. There is no "good enough Ring 1" that justifies skipping Ring 3.

Observed failure mode: after completing Ring 1 (Peec MCP + brand-context skill + web searches), the agent jumped directly to Strategy with 70 prompts and a full allocation table based on commercial intuition — zero external data, zero baseline seed-and-harvest, zero Ring 3 user ask. The rule existed three times over (§6, §8.3, §15.1 checklist). All three layers failed under context pressure. The fix is structural: §8.4 and §9 now enforce a visible intake summary gate (see those sections). This principle explains why the gate exists.

Recurrence after structural fix. The same failure mode recurred even after §8.3 was restructured into named paths (§8.3.1/§8.3.2/§8.3.3a–c). When discovered mid-run, recovery is not optional. Three named shapes govern what the failure looks like; §3.9 governs how to recover.

The three named skip shapes:

1. Outright omission — the intake step was simply not run, either by not asking at all or by asking with partial coverage of the required fields.
2. Substitution on recovery — the skipped step was noticed, but the agent filled the gap with web search / commercial intuition / another Ring's data rather than running the step it was meant to.
3. Planned deferral to Loop 2 — the skipped step is documented as a deliberate design choice: "we'll layer external data in during Loop 2". This is the most dangerous shape because it passes every existing gate by accepting "documented" as equivalent to "dispositioned". The agent names the gap, justifies the deferral with workflow-aware language ("seed-and-harvest first; enrich later"), writes it into the strategy, and ticks §15.1's "external data acknowledged, not hidden" box — and none of that is the user actually sharing data.

All three are failures of the same rule: Intake is a prerequisite for Strategy, not a parallel track. "We'll cover it later" is not a Strategy input — it's deferred intake, and Strategy has to wait. If external data genuinely isn't available for Loop 1, the user must explicitly decline in writing and take ownership of the gap; the agent cannot self-grant the deferral.

3.9 Recovery from intake-step skip is a user-ask, not a substitution

When a §8.3 intake step is discovered to have been skipped, the recovery action is to ask the user for the data the skipped step was meant to elicit — not to substitute web search, not to swap in a baseline-path seed-and-harvest, not to claim the external data was covered elsewhere. Substitutions move the skip from "obvious" to "hidden"; the user has no way to see that Ring 3 was never completed. The structural enforcement at §8.4 depends on the user-ask step producing real user input, not synthetic substitutes.

What recovery looks like:

1. Pause whatever phase discovered the skip.
2. Name the skip in-session: "I see Ring 3 external data intake was skipped — I need to run that now before the Strategy can be trusted."
3. Run the user-ask in the mode the skipped step specifies (batched AskUserQuestion for Ring 3 §8.3.3b; attachment request for §8.3.1 data dump paths).
4. Only after the user has actually provided the data (or explicitly declined and taken ownership of the gap in writing) may the skill proceed.

Recovery via web search, baseline activities, or "I'll just note the assumption" is a repeat of the original failure with a new coat of paint.

3.10 "Ring" numbering names a path, not a fixed step order

Ring 1 / Ring 2 / Ring 3 in §8 name data-source paths, not a linear step sequence. Ring 1 = automated via connected tools, Ring 2 = baseline seed-and-harvest, Ring 3 = batched user ask. They run in parallel or in whatever order the project state demands — there is no "Ring 2 comes after Ring 1". Skills referencing the rings should phrase them as paths ("the Ring 3 user-ask path", "the Ring 1 automation path"), never as ordinals that imply completion of N before starting N+1.

The numbering is kept for continuity with existing references, not because it encodes a sequence. When planning intake, pick the paths the project state activates and run them concurrently where the tools allow.

---

4. Core principles

4.1 Quality over quantity

Fewer well-chosen prompts always beat many marginal ones. Every prompt that doesn't earn its slot costs two things: Peec plan credits, and analytical noise that obscures signal from the prompts that matter.

The test each prompt must pass: "Does this prompt measure a question a real customer would ask on the way to a purchasing decision?" If the answer is "only loosely" or "for completeness", cut it.

4.2 Every prompt earns its slot

Slots are allocated based on data, not intuition. Demand signals (GSC click share, revenue-by-landing-page, CPC × SV, AI-fanout patterns) determine how many prompts a category deserves. Categories without external demand signals don't get slots just because the brand offers the product — they may be a content problem, not an AI visibility problem.

4.3 Automated sources first, user asks last

The agent must check what it can already access before asking the user for anything. Connected MCPs (Peec, analytics, search-console tools, SEO tools, commerce platforms, crawl tools), other loaded skills (brand dossiers, business context), and earlier conversation context all take precedence. The user is asked for manual input only as a batched fallback when no automated path exists. When asking, ask once, ask for the maximum useful batch, and never trickle questions across the session.

4.4 Data persistence

Any data the user provides manually — domain lists, market priorities, taxonomies, customer-voice samples, regulatory notes — is saved to the persistence store so the user never has to provide it twice. On subsequent runs, the agent reads the saved data first, surfaces it to the user, and asks only whether it needs refreshing. See §7 for the persistence mechanism (and note that the mechanism itself is agent/user choice per §3.7).

4.5 Prescriptive strategy, explicit overrides

The Strategy phase outputs a concrete recommendation the user accepts or rejects — not a menu of options with trade-offs. Each recommendation is paired with an explicit "Override this if…" block that lists the common departures. The user reads the recommendation, accepts, or calls out an override. No "which would you like" questions during the strategy phase.

4.6 Brand list reflects reality

Peec's auto-selected competitors are usually wrong — they skew toward information sites (forums, wikis, magazines) rather than actual commercial rivals. The real competitors are domains that actually get cited when AI models answer prompts in the brand's space. On day 0, derive the competitor list from the brand's own commercial knowledge plus any available SERP-competitor or citation data. On existing projects, derive from get_domain_report + get_url_report.

When reading these reports to classify domains as own / competitor / editorial, remember that classification is a returned column, not a server-side filter (see peec-ai-mcp §7.31). Filter by domain with the full owned-TLD list (see peec-ai-mcp §7.10 and §8.10 steps 1/3/5) and do any OWN/CORPORATE/EDITORIAL slicing client-side. Column names also differ between the two reports (retrievals on URL, retrieval_count vs retrieved_percentage on domain — see peec-ai-mcp §7.39); check the payload before sorting or summarising.

Three categories, not two. The brand roster has three shapes, not the binary "competitor vs marketplace noise" the skill's earlier wording implied:

1. Commercial competitor — a distinct business the own brand is fighting for the same customer's wallet. Add to the roster with is_own=false; it will drive share-of-voice, gap reports, and competitive narrative.
2. Assortment brand — a brand stocked by the own retailer (i.e. it appears as a product line on the own site, often at /collections/{brand} or as a category page). Retailing the brand does not make it a competitor; conflating the two inflates competitor counts and corrupts gap analysis. Assortment brands can still matter for visibility tracking (a user searching for the brand may land on the retailer) but should be tagged as assortment so the Strategy-phase output surfaces them distinctly.
3. Marketplace / generic noise — Amazon, Google Shopping, generic directory pages. Not a competitor; not stocked; just co-retrieval noise.

§9.2 codifies the classification step to run before adding any brand to the roster, and §9.3 specifies how assortment brands should map to topics (usually as sub-topics under the parent commercial category, not as first-class topics of their own).

4.7 Tags serve analysis, not categorisation

A tag taxonomy should be 2–3 dimensional (intent × funnel × category is a common shape) and total 15–25 tags. More than that and consistency breaks down. Every prompt should carry at least one tag from each dimension. Avoid tag-dimension duplication (e.g. a transactional tag and a funnel:decision tag are the same signal — pick one).

4.8 Topics mirror business structure

Topics are the coarse grouping used for dashboards and reporting. They should map to the brand's internal structure so stakeholders can find their area. Don't duplicate categorisation between topics and tags — let topics carry business structure and tags carry cross-cutting dimensions. 5–8 topics covers most single-market e-commerce projects; more than 10 usually signals either multiple markets mashed together or topics acting as tags.

Topics are categories, not brand names. A topic should name a category the own brand sells into (e.g. "running shoes", "specialty coffee beans") — never a commercial competitor's brand name. A prompt mentioning a competitor belongs under the category topic that prompt is about; the competitor's name belongs on the brand roster (§4.6 / §9.2). Assortment brands are the nuanced case: if the own retailer merchandises by brand (e.g. a sneaker store with per-brand landing pages for Nike, Adidas, New Balance), it may make sense to use those brand names as sub-topics or as tags rather than as first-class topics. Prefer the tag approach unless the brand roster is very small and assortment-brand coverage dominates the commercial structure.

4.9 Model coverage is plan-gated, not freely chosen

On TRIAL and lower-tier plans, Peec caps which engines actively run. The strategy recommendation must detect plan tier (via active-engine count from list_models with is_active=true) and route accordingly:

• Plan permits engine choice: pick engines matching audience, rotate off inactive ones.
• Plan caps active engines: the question flips to "am I getting maximum signal from the engines I do have?" — mostly a prompt quality and brand-detection hygiene question, not an engine selection one.

4.10 Branded and non-branded prompts are different KPIs

This section applies the instrument-separation principle (§3.1) to KPI reporting specifically — see §3.1 for the underlying rule.

Rolling branded-prompt visibility (questions that name the brand) into overall visibility inflates the headline number. A project with 10 branded prompts that score near 100% and 90 non-branded prompts at 10% looks like it has ~20% visibility when the real "unprompted discovery" visibility is 10%. Branded and non-branded metrics must be reported separately. Keep branded prompts small in count (5–10) and consistently tagged so filters work.

4.11 Direct writes, no dry-run artifact

The skill writes directly to the Peec project rather than producing an intermediate operations list. The strategy sign-off artefact — produced before writes begin — is the audit trail. User sign-off happens before writes begin; verification happens after, using list_* reconciliation.

4.12 Fresh prompts need time

Prompts start collecting data within 24 hours. The default iteration pace is daily — the next Analyse loop can run ~24 hours after writes. For trend-level analyses (SoV shifts, sentiment drift), 7–14 days produces more stable signal. Don't run Analyse in under 24 hours — the data won't be there yet. See §12.7 for the full measurement-window guidance and §3.4 on why calendar time is a first-class resource.

---

5. Relationship to other skills

Skill	Role
peec-ai-mcp	Companion. Covers Peec MCP tool mechanics, OAuth setup, schema quirks, gotchas. Strongly recommended — the Peec MCP has non-obvious quirks that this skill's cross-references depend on.
External-data skills (varies)	Any skill the user has for pulling search-console data, SEO-tool data, crawl data, trends data, or analytics data. This skill consumes their output; doesn't reinvent them.
Brand-context skills (varies)	Any skill the user has loaded that holds accumulated knowledge about the brand being tracked (brand dossier, project-context skill, or similar — however it's named in the agent's environment). Contains prior-captured context (markets, TLDs, revenue profile, regulatory notes) that bypasses intake questions. Always check.

The peec-ai-mcp companion is strongly recommended but not required. It's published at github.com/rebelytics/peec-ai-mcp. Running this skill without it still works, but several tool-level quirks this skill cross-references (classification vs server-side filtering, column name inconsistencies across reports, the 24-hour refresh cadence, update_prompt partial-update semantics, and more) will be rediscovered the hard way. Load both when possible.

---

6. Workflow overview

The workflow runs as Phase A (iterative) plus an optional Phase B (terminal). Phase A is where all the Peec configuration work happens; Phase B is an opt-in stakeholder deliverable at the end.

Phase A — iterative loop

Each loop runs four sub-phases in sequence:

1. Intake (§8). Gather everything the strategy needs. Three concentric rings on the first loop, run as parallel paths (§3.10): automated tools (Ring 1), a baseline path as the floor (Ring 2), and a batched user-provided data ask (Ring 3). Outputs a populated intake state, persisted per §7.
2. Strategy (§9). Convert intake into a prescriptive recommendation with explicit override callouts. User signs off (format agent/user choice). Outputs the strategy sign-off artefact.
3. Write (§12). Execute the signed-off strategy as direct writes to the Peec project via the Peec MCP. Outputs a configured project and a verification log.
4. Analyse (§13). Read what the Peec data actually says after the writes have settled. Produce findings (format agent/user choice) that feed the next Strategy iteration.

Loop-awareness. The first loop runs the full three-ring intake (§8). Subsequent loops typically run a Peec-only intake refresh — re-reading current project state — unless findings or the user surface a gap that needs external data, in which case Ring 2 or Ring 3 is re-entered for that specific gap. Strategy, Write, and Analyse run every loop, with scope narrowed to what changed.

Termination. Phase A ends when findings no longer produce material action for the next Strategy iteration — the strategy has stabilised. That's also when Phase B becomes relevant.

Phase B — optional, terminal

Once Phase A has stabilised, the agent proactively offers a stakeholder-facing presentation of the strategy and its findings (see §14.5 for the timing rules). Phase B is a single pass from existing Phase A artefacts — it doesn't re-do any Phase A work. See §14 for the full rules, including why Phase B is intentionally terminal rather than mid-engagement.

Routing by project state

Phase A's Write sub-phase routes on project state:

• New project (zero prompts at first loop) → first Write is pure creates.
• Existing project → first Write uses the prompt disposition framework (§10) — six buckets covering what to keep, retag, reframe, or remove.

Subsequent loops always run in existing-project mode; the disposition framework is reapplied to the prompts that have been in place long enough to have meaningful data.

Pacing disclosure at intake

At the start of the first Intake loop, the agent surfaces the iterative model and the iteration cadence to the user:

• The default pace is daily iterations — Peec processes new prompts within 24 hours, so the next Analyse loop can run the following day (see §12.7).
• For trend-level analyses (SoV shifts, sentiment drift), a 7–14 day window produces more stable signal and can be used when the question requires it.
• The number of loops is driven by findings, not by a preset timeline.
• Once the strategy has stabilised across a few iterations, the agent can produce a polished stakeholder-facing presentation of the strategy and its findings (Phase B, §14). That comes later — first the tracking needs to be right. Phase B is not committed to at intake, but the user should know the capability exists.

This framing sets expectations before the user has anchored on a linear "do it once and we're done" model.

---

7. Data persistence

User-provided data is saved between runs so the user provides context once, not once per session.

What, not how. This skill requires that intake state persists; it doesn't require a specific file format or directory layout. The intake.yaml schema below is one concrete example. Other equally valid approaches: handoff docs pasted session-to-session, memory systems, journal-style markdown notes, or whatever fits the user's environment. In environments without persistent storage (web chat interfaces), a detailed handoff doc at the end of each session is required so the next session can resume without re-entering data.

The principle: every loop should be able to read the previous loop's intake state, strategy sign-off, and findings without asking the user to re-provide them. The mechanism is agent/user choice.

7.1 Where data is saved (illustrative layout)

<workspace>/<brand-folder>/peec-strategy/
  intake.yaml                — current intake state (canonical, read first)
  intake-history/             — dated snapshots for diffing
    intake-YYYY-MM-DD.yaml
  strategy-YYYY-MM-DD.md     — strategy sign-off artefact for loop N (optional)
  findings-YYYY-MM-DD.md      — Analyse output for loop N (optional)
  verification-YYYY-MM-DD.md  — post-write reconciliation log

This is one concrete example, not a mandated structure. If no brand-specific folder exists yet, ask the user which folder name to use (defaulting to a slugified form of the brand name) and create the structure. If a brand-specific directory already exists from other work, nest peec-strategy/ inside it rather than creating a parallel tree.

7.2 What intake.yaml holds (illustrative schema)

The schema below uses a fictional brand — Northwind Coffee Co., a specialty coffee retailer with European markets and sister brands in tea and brewing equipment — purely as an illustrative example. Adapt the field set to the brand being tracked.

brand:
  name: Northwind Coffee Co.
  primary_domain: northwindcoffee.com
  owned_domains:
    - northwindcoffee.com
    - northwindcoffee.de
    - northwindcoffee.co.uk
    # ... all TLDs
  aliases:
    - Northwind Coffee
    - Northwind Roasters
  regex: null
  regulatory_context: null   # populate if the brand operates in a regulated
                             # vertical (pharma, financial products, etc.);
                             # null for non-regulated brands like this one

markets:
  - country_code: DE
    priority: 1
    revenue_share_pct: 42
  - country_code: UK
    priority: 2
    revenue_share_pct: 28
  - country_code: NL
    priority: 3
    revenue_share_pct: 15

competitors_known:
  - name: Contoso Coffee
    domains: [contoso-coffee.com]
    aliases: []
    relationship: direct_competitor
  - name: Northwind Tea
    domains: [northwindtea.com]
    relationship: sister_brand   # ← persisted, routes differently in reports

sister_brands:
  - Northwind Tea
  - Northwind Brewing Equipment

existing_taxonomy:
  source: supplied_csv
  provided_on: 2026-04-20
  tag_dimensions:
    - intent
    - funnel
    - category

customer_voice_samples:
  provided: false
  last_asked: 2026-04-20

data_sources_connected:
  - peec_mcp
  - brand_context_skill: northwind-coffee-context   # generic name — use
                                                    # whatever the loaded
                                                    # brand-context skill is
                                                    # called in the agent's
                                                    # environment
  - web_search_web_fetch
  # optional enrichments marked absent if not available:
  - gsc: not_connected
  - seo_tool: not_connected
  - analytics: not_connected

# Per-source disposition — mandatory table, one row per Ring 3 data category.
# Each row records whether that data was received, explicitly declined in
# writing, or is still outstanding. No row may be "deferred to Loop 2" as a
# self-granted skip — only the user can decline.
ring3_data_disposition:
  - source: xml_sitemap
    status: received       # received | declined_by_user | outstanding
    provided_on: 2026-04-20
  - source: gsc_queries
    status: declined_by_user
    declined_reason: "No GSC access; will run on later loop after access set up"
  - source: gsc_pages
    status: outstanding
  - source: keyword_tool_export
    status: outstanding
  - source: revenue_by_landing_page
    status: outstanding
  - source: margin_by_product_line
    status: outstanding
  - source: crawl_export
    status: not_applicable  # use when no crawl tool is available for this project
  - source: customer_voice_samples
    status: outstanding
  - source: competitor_faq_urls
    status: outstanding
  - source: brand_positioning_doc
    status: received
    provided_on: 2026-04-20
  - source: regulatory_notes
    status: not_applicable  # non-regulated vertical

last_refreshed: 2026-04-20

The schema is illustrative. Use whatever structure fits — the requirement is that future loops can read it without re-asking.

The ring3_data_disposition table is not illustrative — it is mandatory. Every Ring 3 data category must appear as a row with a disposition of received, declined_by_user, outstanding, or not_applicable. "Deferred to Loop 2" is not a valid disposition — if data isn't available for Loop 1 and the user hasn't declined in writing, the correct state is outstanding and Strategy cannot proceed until it becomes received or declined_by_user (see §3.8 / §3.9 / §8.4). This is the persistence-layer enforcement that closes the "planned deferral" skip shape (§3.8).

7.3 Refresh logic

On each loop, the agent:

1. Reads the persisted intake state.
2. Calculates age: last_refreshed vs today.
3. If age > 90 days, prompts the user to confirm refresh of any field that may have drifted (markets, competitors, revenue share).
4. If age ≤ 90 days, surfaces the existing data to the user in the next Strategy iteration without re-asking.
5. Persists any new fields provided this session, saving a dated snapshot before overwriting the canonical file.

The user should never be asked for data that's already persisted unless the data is stale or the user explicitly wants to update it.

7.4 Handoff-doc fallback for non-persistent environments

In environments without persistent storage (web chat interfaces), the agent must produce a handoff doc at the end of each session that captures:

• Current intake state (brand config, markets, competitors, regulatory context).
• Latest strategy sign-off summary.
• Latest findings and what they imply for the next loop.
• Earliest sensible re-analysis date (per §12.7).
• Pending verification items.

The next session starts by reading the handoff doc back in. This is less seamless than a persistent file, but preserves the core requirement: don't re-ask for data the user has already provided.

---

8. Phase A — Intake

Goal: populate the intake state and the project-state snapshot for this loop.

First loop runs the full three-ring intake below: Ring 1 first, Ring 2 as the floor, Ring 3 as the only user-facing ask.

Subsequent loops typically run a Peec-only refresh — re-reading list_brands, list_topics, list_tags, list_prompts, and the current-state summary — unless a finding from the previous Analyse (§13) surfaces a gap that external data could close. In that case, re-enter Ring 2 or Ring 3 for that specific gap only. The skill does not require re-running the full three-ring intake on every loop.

Pacing disclosure (see §6): at the first Intake, the agent tells the user that the default iteration pace is daily (Peec processes new prompts within 24 hours), that longer 7–14 day windows are available for trend-level analyses, that the number of loops is driven by findings rather than a preset timeline, and that once the strategy stabilises the agent can produce a stakeholder-facing presentation (Phase B, §14).

8.1 Ring 1 — Automated via connected tools and skills

Before touching the user, check each of these. Skip any that isn't available; don't ask the user whether they're available — inspect the environment.

Known MCP gaps — check before asking the user

Before asking the user for any information, the agent must attempt to derive it from the Peec MCP. Several fields that seem like they should be available are not. The table below enumerates the known gaps so the agent checks, confirms the gap, and frames the user ask as "the MCP doesn't expose this" rather than "tell me":

Field	MCP tool to check	What it returns	Gap
Project country / market	list_projects	{id, name, status} only	No country, language, or market metadata at project level. Ask the user: "Peec's MCP doesn't expose project-level market data, so I need to confirm: which markets should this strategy prioritise?"
Plan tier / prompt credits	list_projects	{id, name, status} only	No plan data. get_credit_balance does not exist (see peec-ai-mcp §7.37). Ask the user: "Peec's MCP doesn't expose plan credits. How many prompts does your plan allow?" Single precise question, not a multi-tier multiple choice.
Active engine count (proxy for plan gating)	list_models(is_active=true)	Active engine list	✓ Available. 3 or fewer = likely plan-capped (§9.6).

When asking the user about a known MCP gap, always prefix with the reason: "The Peec MCP doesn't expose this at the project level, so I need to confirm with you:" — this reframes the ask from "I didn't check" to "the platform doesn't expose this" and teaches the user where the gap lives. Persist every answer to the intake state (§7) so subsequent loops don't re-ask. Surface plan-related questions (prompt credits + engine count) together so the user answers all plan constraints in one go.

Peec MCP (always available when this skill runs)

Capture:

• list_projects — confirm the project ID to operate on.
• list_brands(project_id) — own brand flag, domains, aliases, regex, current competitor roster. Note per-brand missing config (aliases: null, regex: null, domain coverage gaps).
• list_topics(project_id) — current topic structure and count.
• list_tags(project_id) — current tag taxonomy, count, dimension coherence (look for overlap like transactional vs funnel:decision).
• list_prompts(project_id, limit=10000) — full prompt inventory with text, tag_ids, topic_id. Pagination matters — see peec-ai-mcp §7.18 (default is 100 per page, silent truncation if missed).
• list_models(project_id, is_active=true) — active engines. Count gates the model-coverage branch (§9.6): 3 or fewer ⇒ likely plan-capped.
• If the project has existing chats, pull a small recent window (list_chats + list_search_queries) to seed fanout mining in Ring 2.

Resulting project-state classification:

• New project: zero prompts, auto-suggested brands still present. The Write sub-phase (§12) will be pure creates.
• Existing project: prompts already in place. The Write sub-phase (§12) will use the disposition framework (§10).

Loaded skills

Scan the active skill list. Specifically check for:

• Brand-context skills — any skill that holds accumulated knowledge about the brand being tracked (brand dossier, project-context skill, or similar — however it's named in the agent's environment). Captures markets, TLDs, revenue profile, regulatory notes, sister-brand relationships.
• Portfolio / group-context skills — where the brand is part of a larger group, the agent may have a shared-context skill covering sister brands, shared infrastructure, and group-level strategic themes.
• Business-strategy / commercial-context skills — any skill capturing the commercial priorities, capacity, or revenue goals that inform allocation decisions.

If a brand-context skill exists, read it first and populate intake state from it before asking the user anything.

Conversation context

Scan the current session transcript for already-provided context — brand name, markets, strategic priorities, known competitors. Populate intake state from this before re-asking.

Optional connected MCPs (skip if not connected)

• GSC MCP — pull top queries over 12 months per market via the API (not subject to the ~1000-row UI export cap; pull several thousand if useful). Filter for question-shaped queries (how|what|why|is|does|should) and commercial intent. Feeds the volume-signal and allocation steps in the Strategy sub-phase (§9).
• SEO-tool MCPs — CPC × SV for commercial weighting, SERP competitors for the brand's keyword universe, AI Overview presence flags.
• Analytics MCPs (GA4, Adobe, Matomo, Piwik Pro, or equivalent) — landing-page sessions, key events, revenue. The strongest commercial signal for e-commerce — prioritise over keyword-demand signals where both are available (see §8.2).
• Commerce-platform MCPs — revenue by category, product catalogue.
• Crawl-tool MCPs (Screaming Frog, Sitebulb, or equivalent) — content inventory, page type distribution, structural content gaps.
• Community/forum access (MCP or agentic browser extension) — community question-mining. If any such tool is connected, use it; Reddit in particular is not directly accessible via the baseline web tools (see Ring 2 notes).

8.2 Ring 2 — Baseline path (always works, no external dependencies)

When Ring 1 returns a sparse picture, the baseline path produces enough signal to build a competent strategy. Every agent running this skill can execute all six steps — no MCPs beyond Peec, no user-specific tool access.

Step A: Peec seed-and-harvest (primary day-0 signal)

This is the load-bearing step for new projects and the richest free-standing demand signal available.

1. Day 0: create 10–15 deliberately broad discovery prompts across the brand's rough topic clusters. Prompt shapes should be generic: "what is X", "best X for Y", "X vs Y", "recommendations for X", "how to choose X". Tag them seed:harvest and set country_code from the primary market. These prompts join the 24-hour cycle immediately (see peec-ai-mcp §7.6).
2. Day 1 (~24 hours later): for each seed chat, call list_search_queries(chat_id=...). This returns the sub-queries the AI engine fanned out to when answering. This is the highest-fidelity demand signal available without paid tools — it's what the AI itself considers the adjacent questions in the category.
3. Also call list_shopping_queries(chat_id=...) for any shopping-mode chats — commercial-intent queries, often product-specific.
4. Mine the fanout for platform patterns: site:reddit.com, site:amazon.*, site:youtube.com, site:quora.com. These are the platforms the AI believes hold answers in the vertical. High Reddit fanout with no brand presence on Reddit is a distribution signal (see §11 pattern library).
5. Seed prompt lifecycle: at Strategy time (§9), decide per seed prompt — keep it if it fits the final strategy and the topic survives, delete it if not. Seed prompts are not automatically preserved.

For existing projects, the seed-and-harvest step is optional — fanout data can be mined from existing chats instead. Use seed-and-harvest when the existing prompt set doesn't cover a category the strategy needs to explore (e.g., the brand is entering a new vertical).

Step B: Competitor FAQ scraping

For each of the brand's top 3–5 known commercial competitors:

1. WebSearch("[competitor name] FAQ") — finds the competitor's FAQ URL.
2. WebFetch(<faq url>) — extracts the question headings.
3. Supplement with WebSearch("[competitor name] blog") for top listicles; WebFetch the most prominent for H2/H3 question structures.

Competitor FAQs are the most direct supply-side signal of "we get asked this a lot". Limits: corporate domains are nearly always accessible via WebFetch; community platforms (Reddit, Quora) are often blocked — see Step E below.

Step C: AI self-report (coverage check)

The agent uses its own reasoning inline during the session. Prompt:

"For a [brand type] operating in [markets], list 30 question-shaped queries someone might ask an AI model before buying in this category. Include a mix of awareness, consideration, comparison, and purchase-intent queries. Flag any queries that touch regulated or grey-area topics."

Generated inline — no external model call, no artifact, just reasoning. Used as a coverage check: after baseline-path outputs are aggregated, compare against this list to spot blind spots.

This signal is weak relative to fanout data and competitor FAQs, but it's free and instant. Treat it as a gap-check, not a seed source.

Step D: YouTube autocomplete + top video titles

For the brand's top 2–3 categories:

1. WebSearch("[category] YouTube reviews") — surfaces top-ranked videos whose titles are question-shaped.
2. Optionally WebFetch(<youtube url>) on the top 3 results — some video pages return transcripts / descriptions that reveal the question space.

Video is a major AI citation source (ChatGPT and AI Overview cite YouTube heavily in product categories). Video titles are a secondary demand signal.

Step E: Reddit / community signals (only via connected tooling)

Reddit is not directly accessible via the baseline WebFetch or WebSearch tools. As of this skill's current release, WebFetch refuses reddit.com and old.reddit.com at the tool level; WebSearch doesn't support site: operators and doesn't surface Reddit organically for typical queries. Re-test if a later agent / tooling generation unblocks Reddit access.

So Reddit stays out of the baseline path. Three fallbacks:

1. Connected Reddit tooling, if present. If a Reddit MCP is connected, use it. If the agent has an agentic browser extension or equivalent that can browse Reddit directly, use that. Mine the 2–3 relevant subreddits for top-year threads.
2. Peec fanout proxy. If the seed-and-harvest (Step A) shows site:reddit.com in the fanout queries, that's the Reddit-demand signal — delivered through Peec without needing direct Reddit access.
3. User-provided. If the user has scraped or exported Reddit data (rare), consume it via Ring 3.

Quora and Stack Exchange are usually accessible via WebFetch — try them for technical/niche verticals, but don't rely on them for general e-commerce.

Step F: XML sitemap baseline (see §8.3.2)

URL-structure baselining from the XML sitemap is a Ring-2 automated step but is documented once, in §8.3.2, because it precedes the Ring 3 user ask directly. Run it before composing Ring 3.

Step G: User's domain knowledge (batched ask — see Ring 3)

The one user-facing ask happens at the end of intake, not throughout. See Ring 3 for the question set.

8.3 Ring 3 — User-provided data (batched ask at end of intake)

On the first loop, Ring 3 is fired regardless of Ring 1 richness. "The user has no data" is a valid answer; "the agent decided Ring 1 was enough" is not. See §3.8 for why this is a hard rule.

Ring 3 runs in four sub-steps. The sequence enforces §4.3 ("automated sources first, user asks last") structurally rather than by prose alone.

Two structurally different asks — don't collapse into one widget. The Ring 3 user-facing ask has two functionally distinct parts that must not be merged into a single AskUserQuestion call:

• The data request (§8.3.3a) — "please attach these files / confirm each data category is unavailable". Attachment-centric, plain-text, cannot be compressed into a multiple-choice widget. The user needs to see the full list of what they could provide and respond item-by-item.
• The scoping widget (§8.3.3b) — "how many prompts? which markets? which brand priorities?". Binary or short-choice questions well-suited to AskUserQuestion, with explicit override slots per §4.5.

Collapsing these into one widget is the known failure mode: the widget surface can represent scoping choices but not attachment requests, so the data request is silently dropped. The split is load-bearing; keep it explicit.

8.3.1 Automated inventory (before composing the ask)

Before composing the Ring 3 question, the agent must enumerate what data is already accessible for this brand. Check each of:

• Brand-context skills — read each loaded brand-context skill for referenced files, existing tool access, data-layer docs, crawl configs, taxonomy documents.
• Tool-reference skills — check each tool-specific skill for credentials, project IDs, and access patterns that bypass a user export (e.g. a search-console MCP reference, an AI-visibility-platform API reference, an analytics MCP reference).
• Workspace folders — scan the brand-specific folder for CSVs, JSONs, MDs, XLSXs that predate this session.
• Connected MCPs — list every connected MCP tool and note which could supply Ring 3 data (analytics, search console, rank tracking, CRM, community/forum access).

Output: an "already accessible" block in the Intake summary (§8.4), with file paths and tool names. This block feeds the targeted ask below.

8.3.2 Automated URL-structure baseline (sitemap-first)

Before composing the user-facing ask, run the sitemap-based URL structure baseline. This replaces the earlier framing of "ask the user for crawl data" — crawl tools (Screaming Frog, Sitebulb, or equivalent) are the bonus, not the source.

1. WebFetch("<domain>/sitemap.xml") or fetch via bash. If it returns a sitemap index, fetch the top 2–3 nested sitemaps (typically sitemap_pages.xml, sitemap_posts.xml, sitemap_products.xml or similar).
2. Extract URLs and classify by path pattern (product URLs, category URLs, editorial URLs, help-centre URLs). This produces a coarse page-type distribution without crawling content.
3. Feed the distribution into §9.5 (topic structure) and the source authority inputs for §13.9 (URL gap analysis) / §13.15 (own-brand URL citation map).

This is available on every commercial site without user effort and should be the starting point for URL-structure discovery on every project. Where Screaming Frog, Sitebulb, or equivalent crawl data is available (via Ring 1 brand-context skills or Ring 3 user provision), use it to enrich the sitemap baseline — adding page-type-segmentation, broken-link detection, and indexability flags that the sitemap alone can't give you. Crawl data is never a substitute for the sitemap baseline because it's not always available; it's additive when it is.

What the sitemap doesn't replace: internal linking, crawlability data, rendered content, structured-data coverage. When a full crawl is available, prefer it for those specific signals.

Scope caveat: sitemaps may be truncated, outdated, or exclude noindex URLs. Treat the URL list as "publishable pages the site wants indexed", not as the full content footprint.

8.3.3a Targeted data request (attachment-centric, plain text)

After sitemap baselining (§8.3.2), the agent composes the data request as plain text listing every category the user could provide an attachment or export for. This is the "please send me these files" ask — not a widget. Use AskUserQuestion ONLY for the scoping widget in §8.3.3b; the data request must be a separate plain-text message so the user can respond item-by-item with attachments.

Frame each option with what's already known — e.g. "I already have your crawl export and taxonomy doc from the brand folder; do you also have a fresher search-console export or should I use the existing one?" instead of "Do you have crawl data?"

Mandatory template for the data request. The plain-text ask must enumerate every row from the ring3_data_disposition table (§7.2) that is currently outstanding. For each row, state:

• What the data is (plain language).
• How to provide it (CSV attachment, URL, pasted text).
• Why it matters (one sentence connecting to Strategy).
• That "I don't have this / not applicable" is a valid response.

The user's reply then populates the ring3_data_disposition table — each row becomes received (data provided), declined_by_user (user explicitly declined in writing), or not_applicable. Rows the user doesn't address remain outstanding, and Strategy cannot proceed.

The standard categories to check for gaps (skip any already covered by §8.3.1):

1. SEO tool data — Ahrefs, Semrush, DataForSEO, or equivalent. Adds AI Overview presence flags, CPC × SV, SERP competitor context.
2. Search Console data — GSC export or direct access. Top queries over 12 months. Note: the GSC UI export is capped at ~1000 rows. To go beyond that — pull several thousand queries if useful — use the GSC API (directly, or via a connected GSC MCP).
3. Web analytics revenue data — GA4, Adobe, Matomo, Piwik Pro. Landing-page revenue by category. Strongest commercial signal for e-commerce. Handling notes:
   • Exclude navigational / utility from the denominator. Homepage (/), checkout, account, login, password recovery, wishlist, site search results, and loyalty program URLs capture revenue from users who already know the brand and aren't discoverable via AI visibility. Compute category allocation against the "discoverable content" subset only.
   • Classify product detail pages into categories. Product detail pages typically outnumber category pages 10:1 and aggregate to a significant share of revenue. Use URL keywords, breadcrumb structure, or crawl data to classify each product URL into a category — otherwise the allocation table underweights categories that earn their revenue through individual product pages.
   • Watch for transient / price-driven revenue clusters. Sale, clearance, outlet, and discount sections often concentrate significant revenue into a single URL (/sale, /clearance, /outlet). These represent a buying behaviour signal that no keyword tool will surface because they aren't keyword-driven — users respond to price framing. Treat them as their own intent cluster (see §11.15).
   • Understand attribution. GA4's default is last-non-direct click. Categories that sit late in the purchase journey (checkout, account, loyalty) get over-credited; categories early in the journey (blog, informational content) get under-credited. The AI-visibility journey is typically early-to-mid-funnel, so tilt the allocation toward categories that convert from first-visit or mid-journey landings.
   • Don't shrink a category to zero on revenue alone. A category at €0 revenue may still be strategically important (emerging category, category the client wants to enter). Keep 2 diagnostic prompts so the AI visibility gap stays measurable.
   • Cross-check against GSC. If GSC clicks and GA4 revenue agree on rank order, confidence is high. When they disagree, GA4 is usually the better guide for allocation on e-commerce — but note the disagreement in the intake record so the reasoning is traceable.
   • Non-e-commerce equivalent: for services, B2B, or SaaS, the mirror signal is "leads/signups per landing page" or "pipeline value per landing page" from CRM/analytics. Same principle — measure outcome, not demand.
4. Website crawl data — Screaming Frog, Sitebulb, or equivalent crawl export. Page type distribution, content gaps, product/category inventory.
5. Customer-voice data — sales call transcripts (Gong, Chorus, Fireflies), support tickets (Zendesk, Intercom), site search query logs, post-purchase survey text, live chat logs. Even 100–500 rows matters.
6. Brand-specific context — buyer personas, common prospect questions, existing taxonomy, brand guidelines, regulatory notes, competitor intelligence.

8.3.3b Scoping widget (AskUserQuestion)

The scoping widget uses AskUserQuestion for short-choice questions about scope, budget, priority, and positioning. This is a separate call from the plain-text data request in §8.3.3a — don't merge them.

Typical scoping questions (omit any already answered by existing intake / brand-context skill):

• Country scope — single market, primary + secondary, multi-market?
• Prompt budget — how many prompts should the plan cover in Loop 1?
• Engine priority — should the strategy privilege specific engines (e.g. ChatGPT + AI Overview for a DE e-com site) or spread evenly?
• Brand positioning — customer-facing vs. enterprise-facing, premium vs. value, etc.
• Assortment-brand handling (§4.6 / §9.2) — should stocked brands be tracked as roster brands, used as tags, or omitted entirely?

Each AskUserQuestion question should carry an explicit "Override this if…" slot per §4.5, so the user can divert from the recommended default without being trapped in a multiple-choice menu.

8.3.3c Open-ended data-source invitation

At the end of the scoping widget, include an open-ended option: "What other data sources do you think would help? Examples: existing prompt sets in other AI-visibility platforms, industry report subscriptions, internal taxonomy docs, CRM segmentation exports, sales call libraries, etc." This invites user expertise rather than assuming the skill's enumerated list is complete. The user has context the skill doesn't — the skill should invite that context, not cap it.

Ring 3 handling

Two distinct messages in sequence: §8.3.3a (plain-text data request) followed by §8.3.3b (scoping widget). Both must fire before Strategy. Per §3.8, the data request is not optional even if Ring 1 is rich.

If the user provides data, save it to the persistence store (§7) so subsequent runs don't re-ask. Specifically:

• CSV/XLSX exports go under the persistence store's user-provided subdirectory (or equivalent per §3.7 — mechanism is agent/user choice).
• Free-text responses go into the intake state in the relevant field.
• Dated snapshots preserve what was provided when.
• The ring3_data_disposition table (§7.2) is updated row-by-row based on the user's reply — received, declined_by_user, or not_applicable. Rows without explicit disposition remain outstanding and block the Strategy gate.

8.4 Intake summary output (mandatory gate for §9 Strategy)

At the end of the Intake sub-phase, the agent writes:

• Updated intake state (persisted per §7).
• A mandatory intake summary block in the session output. Strategy (§9) cannot begin until this block has been written and contains non-empty entries — or explicit "skipped because …" rationales — for every row below. If any Ring 2 or Ring 3 row is absent rather than explicitly skipped, return to Intake.

Required rows:

• Loop number (first loop vs subsequent).
• Project state (new / existing).
• Ring 1 tools that populated data.
• Ring 2 steps completed (first loop only). Each of Steps A–F must appear with a result or an explicit skip rationale.
• Ring 3 automated inventory (§8.3.1) — what data was already accessible.
• Ring 3 sitemap baseline (§8.3.2) — URL structure extracted from <domain>/sitemap.xml with page-type distribution.
• External data received — itemised. Reproduce the ring3_data_disposition table (§7.2) verbatim, one row per data category, each marked received / declined_by_user / outstanding / not_applicable. This row is the authoritative check that closes the "planned deferral" skip shape (§3.8 shape 3): a blanket "Ring 3 user-provided data: confirmed unavailable" is no longer an acceptable summary — every category must be listed with its specific disposition. If any row is outstanding, return to §8.3.3a.
• Gaps: which data sources returned nothing (and how the strategy will compensate).
• Pre-Write quality gates (§15.1) — the agent must write the checklist results into the Intake summary block verbatim, including ✓ / ✗ marks and the rationale for any ✗. This turns the checklist from an internal practice into a visible artefact the user can inspect.

This block feeds the Strategy sub-phase (§9) and eventually any stakeholder-facing intake-and-data-sources summary in Phase B.

---

9. Phase A — Strategy

Hard gate: Strategy cannot begin until the Intake summary block (§8.4) has been written and contains non-empty entries — or explicit "skipped because …" rationales — for each of: Ring 1 tools used, Ring 2 steps completed (first loop only), Ring 3 automated inventory + user ask, and identified gaps. If any row is absent rather than explicitly skipped, return to §8 Intake. See §3.8 for why this gate exists.

Goal: convert the intake into a concrete, prescriptive strategy recommendation. The user accepts or calls out an override. No menus, no "which would you like" questions.

Every recommendation block follows the same structure:

Recommended: [concrete numbers, categories, or choices]

Reasoning: [1–2 sentences tied to intake data]

Override this if:

• [condition 1] → [what to change]
• [condition 2] → [what to change]
• [etc.]

9.1 Prompt volume split (load-bearing recommendation)

Recommended: 50% discovery, 30% consideration, 15% comparison, 5% branded reputation monitoring. Tag each prompt with funnel:<tier>.

Reasoning: Discovery dominates where the brand needs to attract new customers (the overwhelming majority of Peec use cases). Comparison slots capture head-to-head competitor queries where AI answers frequently rank. Branded reputation monitoring measures how AI describes the brand when asked about it by name — useful, but should never dominate because branded prompts score near 100% visibility by construction (§4.10, §3.1).

Override this if:

• B2B or long sales cycle → flip to 25/45/20/10 (more consideration weight).
• Strong existing brand equity and branded prompts already at visibility=1.0 → drop branded reputation monitoring to 0%, reclaim slots for discovery.
• Regulated vertical (cannabis, pharma, gambling, finance) → add a topic:safety band at ~10%, taken off discovery; expect legal-caution framing in AI responses (see §11 pattern library, regulatory-aware sentiment).
• TRIAL plan or ≤50 prompt slots → drop comparison entirely; focus on discovery + branded reputation monitoring only.

9.1.1 Search-volume axis (orthogonal to the funnel split)

The funnel split above is the primary axis. As of April 2026, Peec exposes a second orthogonal axis via list_prompts.volume — the search-volume ordinal that was previously only visible in the UI is now pullable through MCP (see peec-ai-mcp §7.42). Treat volume as a distinct prompt-portfolio axis alongside funnel stage; a prompt portfolio that's balanced on funnel but dominated by "very low" volume prompts is materially under-weighted for commercial coverage.

Recommended volume mix (within each funnel tier):

• Head (high / very high): 20–30% — tests whether the brand surfaces on the queries that drive the category.
• Mid (medium): 40–50% — the workhorse prompts that carry most of the signal.
• Long tail (low / very low): 20–30% — captures niche / specific intent and keeps long-tail coverage legible.

Reasoning: A portfolio that's all head prompts is great for visibility headlines but hides long-tail gaps; all long-tail misses the queries that actually drive category traffic. The orthogonal distribution means each funnel tier itself has head/mid/tail coverage, not just the roster as a whole.

Override this if:

• Pre-existing TRIAL-tier project with <30 prompts → drop long tail entirely; focus on head + mid so the small budget doesn't fragment.
• Very niche vertical where head-volume queries don't exist (e.g. a specific B2B SaaS category) → the "head" tier may be empty by nature; concentrate on mid + long tail and note the constraint.
• Project whose current portfolio is already ≥80% "very low" volume → Loop 2 should prioritise adding head/mid prompts over adding more long-tail. The volume signal makes this measurable.

Handling the volume ordinal in code. list_prompts.volume returns string ordinals ("very low" / "low" / "medium" / "high" / "very high") — not the 1–5 integers the schema claims. Do not numerically sort or compare without first mapping to integers client-side. See peec-ai-mcp §7.42 for the field behaviour.

Using volume in Analyse. In §13.3 (branded vs non-branded findings), segment visibility by volume tier — "we have 30% visibility on high-volume discovery prompts and 70% on very-low discovery prompts" is a very different story from a flat "50% discovery visibility" headline. Volume segmentation turns a muddled average into a commercially-meaningful diagnosis.

9.2 Country and market scope

Recommended: Start with the top 2 markets by revenue or traffic. Add country_code on every prompt from day 0.

Reasoning: Multi-market is cheap to add now, painful to backfill — every prompt without country_code is a prompt that won't be filterable by market later. See peec-ai-mcp §7.15 — country_code is required on create; there is no language field (language is inferred from text).

Override this if:

• Single-market brand → use one country_code everywhere, but set it explicitly.
• Multi-TLD with shared content across markets → track flagship market first, add others once flagship visibility data exists.
• The brand operates in a country outside Peec's 92-country enum → flag and discuss fallback with the user before proceeding (see peec-ai-mcp §7.15).

9.3 Brand roster

Recommended: Own brand with full owned-domain list + 5 tracked competitors, manually curated.

Reasoning: Peec's auto-selected competitors skew to reference and UGC sites rather than commercial rivals (§4.6). A manually curated shortlist of 5 genuine competitors produces cleaner share-of-voice data than a sprawling 15+ list.

Own-brand configuration

Recommended: For the own brand, set:

• domains = all TLDs the brand operates (not just primary).
• aliases = all common brand-name variants seen in AI responses (e.g. a fuller legal name, a bare domain, or an initials shorthand like "ACME" for "Acme Coffee Company").
• regex = set only if aliases can't capture the variant space (e.g. multiple word-boundary cases). Pass null otherwise.

Reasoning: Multi-TLD own-brand classification (§4.6, and peec-ai-mcp §7.10) — any owned TLD missing from domains will be classified as CORPORATE in domain reports, not OWN. That silently misreads cross-TLD mentions as competitive. Missing aliases are the single most common cause of understated own-brand mentions in Peec.

Override this if:

• Brand genuinely operates only one TLD → single domain is correct.
• Brand has overlapping TLDs with different companies (rare, but possible in regulated trademarks) → omit conflicted TLDs and note in the persisted intake state.

Brand classification step (mandatory, before proposing any roster)

Before proposing a brand as a competitor, classify it against the three-category shape from §4.6:

1. Commercial competitor — distinct business, fighting for the same customer's wallet. Add to the roster with is_own=false; classify in the persisted intake state as direct_competitor, aspirational, or sister_brand.
2. Assortment brand — a brand the own retailer stocks and merchandises (typically appears as a product line at /collections/{brand}, a Shopify collection, or a brand category page on the own site). Detect via a sitemap scan (§8.3.2) for /collections/, /brands/, /manufacturer/, or equivalent path patterns. Retailing the brand doesn't make it a competitor — conflating the two inflates competitor counts and corrupts gap analysis. Surface these separately in the Strategy output so stakeholders see the distinction.
3. Marketplace / generic noise — Amazon, Google Shopping, generic directory pages. Not a competitor; not stocked; skip entirely from the roster.

Assortment-brand handling rules:

• Don't add as a roster competitor by default. Assortment brands inflate SoV denominators and can turn the own retailer's own assortment into a headline "competitor threat".
• Tag, not track (preferred). Tag prompts that mention the assortment brand with a brand:<name> tag so topic/tag-filtered reports can surface per-assortment-brand signal without polluting the competitor SoV.
• Topic sub-structure (alternative, for assortment-heavy sites). If the retailer merchandises by brand as a primary navigation axis (e.g. a sneaker store with per-brand landing pages dominating the URL structure), it may make sense to use those brand names as topics or sub-topics (§9.5). Prefer the tag approach unless the brand roster is very small and assortment coverage dominates the commercial structure.
• User decides. Surface the classification choice explicitly in §8.3.3b (scoping widget) rather than assuming.

Competitor configuration

Recommended: For each of the 5 commercial competitors (not assortment brands — see the classification step above), set name, domains, aliases. Skip regex unless needed. Classify each competitor in the persisted intake state as direct_competitor, aspirational, or sister_brand.

Reasoning: Sister-brand misclassification is a portfolio-brand failure mode (§11 pattern library). A sibling brand in AI responses takes share from the own brand on paper, but the group still wins — reports that don't distinguish sister brands from rivals will systematically overstate competitive pressure.

Override this if:

• Brand is part of a corporate group with sibling brands in the same vertical → prefix sister-brand name with [Sister] in Peec so reports self-document (Peec has no native is_sister flag). Important: when applying this prefix, the aliases array must be populated in the same update call with the original brand name, or brand detection breaks silently — see §11.2 for the full pattern and safe wave ordering.
• More than 5 genuine commercial competitors exist and the plan allows → add up to 10, but treat the extras as secondary in SoV calculations.
• Fewer than 3 real commercial rivals exist (niche / category leader) → populate with 3 aspirational competitors (market leaders the brand wants to benchmark against).

9.4 Tag taxonomy

Recommended: Three axes, 15–25 tags total:

• Intent: intent:commercial, intent:comparison, intent:transactional, intent:informational, intent:branded
• Funnel: funnel:awareness, funnel:consideration, funnel:decision, funnel:branded
• Category: one tag per business category from the topic structure (§9.5), prefixed cat:

Every prompt carries at least one tag from each dimension.

Reasoning: 2–3 dimensional taxonomies stay consistent under growth. More dimensions produce orphaned tags and inconsistent application. Never parallel two dimensions that measure the same thing (e.g. don't maintain both transactional and funnel:decision — pick one).

Override this if:

• Brand already has a taxonomy in use (brand guidelines, GSC query groupings) → mirror it rather than invent a parallel one.
• Regulated vertical → add a regulatory dimension with tags like regulatory:restricted so sentiment reports can filter these out of headline numbers (see §11 pattern library).
• Portfolio brand with sister-brand overlap → add a relationship dimension with relationship:sister vs relationship:competitor so SoV reports can distinguish.
• Tag count would exceed 25 with all planned dimensions → drop the weakest dimension (usually intent or comparison) and fold it into a wider tag.

Taxonomy hygiene check (existing projects only)

For existing projects, before proposing the taxonomy, run a duplication check:

1. For each pair of tags in list_tags, compute the prompt-set overlap (intersection of their prompt IDs, divided by the smaller set).
2. Flag any pair with >60% overlap as a duplication candidate.
3. For each flagged pair, propose which tag to retire and which to keep.

Common overlaps: transactional ↔ funnel:decision, informational ↔ funnel:awareness, branded ↔ funnel:branded.

9.5 Topic structure

Recommended: 5–8 topics for single-market projects. Each topic maps to a business category. Topic names should be clean (no prefixes duplicating tag dimensions — cat:seeds is a tag, "Seeds" is a topic). Topics name categories the own brand sells into — never commercial competitor names (§4.8).

Reasoning: More than 10 topics usually signals either multiple markets mashed into one project (topic-per-market is wrong — that's country_code's job) or topics acting as tags. Every tag that names a prompt cluster larger than ~3 prompts should be considered a candidate topic, not just a tag (§4.8). A competitor brand name as a topic is a strong signal the brand roster (§9.3) isn't classified correctly — competitors belong on the roster with is_own=false, not as topics.

Override this if:

• Multi-category marketplace with genuinely distinct verticals → up to 12 topics is acceptable if each has 8+ prompts.
• Single-vertical specialist → as few as 3–4 topics is fine.
• Existing project has overlapping topics (e.g. "Growing" and "Growing Equipment") → propose a merge with update_prompt.topic_id to move prompts, then delete_topic the redundant one.
• Assortment-heavy retailer where brand names dominate site structure → assortment brand names may legitimately serve as sub-topics or (preferred) as brand:<name> tags; see §9.3's "Brand classification step" for the decision criteria.

Prompt disposition and assortment brands. When reviewing an existing project's prompt set against the new topic structure, watch for prompts whose topic is a brand name. Two sub-cases:

• Topic is a commercial competitor name → move the prompt to the relevant category topic and add a competitor:<name> tag. This preserves the data while routing the signal to the right axis.
• Topic is an assortment brand name → apply §9.3's classification rules. If the retailer merchandises by brand at primary-navigation depth, the topic may be legitimate; otherwise move the prompt to a category topic and tag with brand:<name>.

Either move is a update_prompt.topic_id call (not a text edit — see peec-ai-mcp §7.13 for why text is immutable).

9.6 Model coverage (plan-tier aware)

First, detect plan tier. Count active engines via list_models(project_id, is_active=true). If 3 or fewer, the plan most likely caps model coverage.

Branch A: Plan permits engine choice (4+ active engines available)

Recommended: Match models to audience:

• European B2C retail: ChatGPT (scraper), Google AI Overview (scraper), Perplexity, Grok.
• Developer tools / B2B SaaS: add Claude; drop Grok unless the audience is on X.
• German-speaking / DACH: prioritise Google AI Overview — highest German-language query volume.

Reasoning: Every tracked model inflates chat count and plan cost proportionally. Don't default to "all models" — match audience.

Override this if:

• Developer / technical audience → include Claude and Perplexity prominently; deprioritise AI Overview.
• Global English audience → add Perplexity, drop regional variants.
• Enterprise procurement context → include Copilot.

Branch B: Plan caps active engines (3 or fewer)

Recommended: Accept the active engine set as a constraint. Focus strategy effort on prompt quality, brand-detection config (aliases, regex, domains), and measurement hygiene. Revisit engine selection if upgrading plan.

Reasoning: On a gated plan, "which engines should I track" is the wrong question — that choice isn't yours to make. The right question becomes "am I getting maximum signal from the engines I have?", which is almost entirely about prompt quality and brand configuration (§9.3 own-brand aliases/regex) rather than engine rotation.

Override this if:

• Plan upgrade is under discussion → surface model-coverage gaps as inputs to that decision.
• Active engine set doesn't include any of the brand's priority audience's preferred AI tools → flag and recommend upgrade.

9.6.1 Prompt-credit detection (known MCP gap)

Plan detection has two axes: engines (detectable via MCP — §9.6 above) and prompt credits (not detectable). list_projects does not