research-icp

ICP Research — Orchestrator

Foundational skill for all stacks. Coordinates sub-agents to build audience intelligence from real research, not assumptions. Capability metadata (route triggers, prerequisites, load map, artifact contract) lives in routing.yaml. Why this skill exists, creative-vs-structural framing, 10-gate quality summary: references/playbook.md.

Core question: Who exactly are we talking to and what keeps them up at night?

Critical Gates — load first

Non-negotiable before any agent dispatches:

1. No guessed personas — VoC or interview evidence only. Every attribute traces to product context, brief, user input, or VoC quotes. Fabricated personas mislead 13+ downstream skills.
2. Don't skip habitat mapping. IMC planning needs specific community names with density and engagement type. "They're on LinkedIn" is not actionable.
3. Max 2 personas. More dilutes focus. If 4+ segments surface, force-rank by revenue potential; document cuts in Segment Rationale.
4. Stale product context (>30 days) → recommend re-run. If docs/forsvn/canonical/product/PRODUCT-CONTEXT.md Date is older than 30 days, warn and recommend re-run. Proceeding → note "stale product context" in artifact header.

The source floor (≥5 independent sources/persona), confidence labels, and the mandatory Sample Bias section are critic-enforced (Gates 8–10 below), not pre-dispatch — see the critic checklist + references/confidence-and-bias.md.

Before Starting

Apply references/_shared/before-starting-check.md. Then:

• Mode resolution (references/_shared/mode-resolver.md). budget: deep. --fast collapses to Route A (skips habitat-agent + decision-psychology-agent) IF Warm Start has sufficient context; critic gate collapses to single pass. Cold Start STILL fires under --fast when context is missing — --fast does NOT authorize hallucinating personas (Critical Gate 1 floor).
• references/_shared/execution-policy.md — session execution profile (single-vs-multi)
• Read .forsvn/index/manifest.json — find any prior docs/forsvn/canonical/research/ICP.md (re-run signal) and check docs/forsvn/canonical/product/PRODUCT-CONTEXT.md staleness (Gate 4).
• Run Pre-Dispatch per references/procedures/pre-dispatch.md — auto-scan, Warm/Cold Start, 5-question Cold Start prompt, read order, Write-back map.

Quality Gate — critic checklist (9 of 10 gates)

Gate 7 (Brief Alignment) is critic-agent-only — it needs the originating brief. Full 10-gate rubric in agents/critic-agent.md.

• Every VoC quote includes platform name and traces to a real source (not agent-generated)
• Each persona has a habitat map with specific channels and supporting evidence. Aim for 3+; document why if fewer.
• Each emotional driver traces to at least 2 specific quotes
• Decision psychology names specific cognitive biases and objections (not generic "they need trust")
• At least 15 VoC quotes across categories
• Maximum 2 personas
• Every finding carries [Confidence: H | M | L | sources: N] per references/confidence-and-bias.md. No unresolved L shipped.
• Sample Bias section present and specific to this dataset. Generic disclaimers FAIL.
• Each persona meets the ≥5 independent-sources floor. Below 5 → NEEDS_CONTEXT (or --hypothesis-mode with logged override).

Artifact Contract

• Paths: docs/forsvn/canonical/research/ICP.md (canonical audience record, id: icp-research) + docs/forsvn/canonical/product/PRODUCT-CONTEXT.md (canonical foundational record, id: product-context — research-icp IS the producer).
• Lifecycle: canonical — edited in place; on re-run overwrite in place and bump the integer version: (no .v[N].md sibling — git history holds priors).
• Frontmatter: skill, version, date (ISO-8601), status, stack: research, review_surface: html, id: icp-research, type: canonical, keywords: [icp, persona, audience, voice-of-customer, pain, habitat]. See references/_shared/artifact-contract-template.md for the full schema.
• Required body sections (in order — cross-stack contract): Persona 1 (Demographics + Pain Profile + Decision Psychology + Habitat Map) · Persona 2 (if applicable, max 2) · Top 3 Emotional Drivers · Red Flags · Next Step. Full template (60+ lines): references/format-conventions.md.
• Optional sections: Segment Rationale (3+ segments surfaced, 2 cut per Gate 3) · Known Issues (critic FAILed twice and artifact ships with annotations).
• Side effects (mandatory on PASS / done_with_concerns):
  • Write docs/forsvn/canonical/research/ICP.md.
  • Write or update docs/forsvn/canonical/product/PRODUCT-CONTEXT.md (8-section schema + Canonical Terminology).
  • Experience write-back per procedures/pre-dispatch.md Write-back map: Q1 → experience/product.md + mirror to docs/forsvn/canonical/product/PRODUCT-CONTEXT.md Product section; Q2/Q3/Q4 → experience/audience.md. Q5 (Route) is NOT persisted — routing only.
• Consumed by: plan-campaign · create-brand · write-copy · brief-landing-page · brief-graphic · write-ad · write-outreach · research-shortform · brief-shortform · humanmaxxing · optimize-seo · polish-vn · write-social.
• Cross-stack OUTPUT contract: Artifact Template structure + Habitat Map 5-column schema + Top 3 Emotional Drivers + Next Step block + PRODUCT-CONTEXT.md 8-section schema are load-bearing — schema changes require atomic update of 13 downstream consumers (anti-patterns.md row "Cross-stack contract drift").

Chain Position

Previous: none (or any skill needing audience context — Route C) | Next: plan-campaign, create-brand.

Foundational role: Creates docs/forsvn/canonical/product/PRODUCT-CONTEXT.md consumed by 13+ downstream skills. Run first for significantly better downstream output.

Re-run triggers: audience pivot, new market entry, major product changes, quarterly for active products.

Skill deference: competitive analysis / market sizing → research-market. Campaign planning from personas → plan-campaign. Brand identity using audience data → create-brand. Business-problem diagnosis → diagnose.

Routing + Dispatch

Three routes (A / B / C) — chosen at Pre-Dispatch (Cold Start Q5 or auto-inferred per procedures/pre-dispatch.md § Route Selection). Agent table + route graphs + pattern-catalog map: references/agent-manifest.md. Full 6-step Dispatch Protocol + single-agent fallback + critic FAIL routing: references/procedures/dispatch-mechanics.md.

Anti-Patterns

Read references/anti-patterns.md before output ships — 12 named anti-patterns (7 from original body + 5 cross-cutting: hallucination under --fast, canonical product-context.md mirror skip, Q5 routing-persistence, cross-stack contract drift, write-back skipped/partial). Detection + bad/good examples + verified agent ownership against critic-agent.md Rewrite Routing Table.

Durable Rules (protected)

Completion Status

• DONE — full ICP synthesized, critic PASS, all 5-7 dimensions populated with quoted evidence.
• DONE_WITH_CONCERNS — critic PASS but Route A used (habitat/decision-psychology omitted), OR VoC quote density thin (flagged in artifact).
• BLOCKED — irreconcilable persona contradictions (e.g., two distinct buyers with no merge path); needs user scope decision.
• NEEDS_CONTEXT — docs/forsvn/canonical/product/PRODUCT-CONTEXT.md missing AND user can't describe product/audience; recommend /discover first.

References

• references/playbook.md — why, creative-vs-structural framing, foundational-role inventory, when NOT to use
• references/agent-manifest.md — agent table, 3 routes, pattern-catalog map
• references/_shared/before-starting-check.md, mode-resolver.md, pre-dispatch-protocol.md, confidence-labeling.md
• references/procedures/pre-dispatch.md, dispatch-mechanics.md
• references/format-conventions.md, anti-patterns.md, confidence-and-bias.md
• Pattern catalogs: voice-of-customer.md, customer-interviews.md, habitat-mapping.md, icp-to-imc-handoff.md
• Walkthrough: references/examples/icp-walkthrough.md