@antoneeo/mkt-agentic-sdlc-skill 0.2.0

package/skills/mkt-agentic-sdlc/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: mkt-agentic-sdlc
+description: Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger, adversarial CMO review, a complete Standalone mode and optional symbiosis with devPNT. Use for marketing plans, go-to-market strategy, campaign planning and market research.
+author: Antonio Pinto (https://github.com/Antoneeo)
+copyright: (c) 2026 Antonio Pinto
+---
+
+# Marketing Agentic SDLC
+
+This skill guides marketing strategy work with an Evidence-First process proportional to the engagement. It turns the agent into a disciplined marketing strategist: facts come from the user, analysis comes from real research, numbers come from a ledger, and the plan ships only after mechanical validation and adversarial review. It must work fully even without devPNT. When devPNT is available and configured for the current project, plans and strategy artifacts become governed, versioned documents with proposal/approval workflow.
+
+Support files in the skill directory:
+- `frameworks.md`: which professional framework to use in which phase (SOSTAC, STP, JTBD, positioning, KPI tree) — and when NOT to use one.
+- `elicitation.md`: the question waves and the only-facts-you-own rule.
+- `research.md`: the research playbook and the evidence ledger discipline.
+- `templates.md`: templates for every artifact and deliverable.
+- `review.md`: the CMO review discipline and the marketing red-flag battery.
+- `scripts/mkt_check.py`: mechanical validator (`check`, `validate`, `ledger`, `budget`, `funnel`, `trace`, `index`).
+- `ENFORCEMENT.md`: optional setup for CI and hooks.
+
+Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
+
+## Honesty Contract
+
+No process guarantees market success, and this skill never claims one. What it guarantees is **process rigor**: zero invented numbers, internal mathematical consistency, conformance to frameworks professionals recognize, measurability of every commitment, and a built-in control loop. State this plainly if the user asks for a "guaranteed" outcome — the guarantee is the rigor, not the market.
+
+## Marketing Values
+
+- **Evidence before claims:** no market number, benchmark or persona trait enters an artifact without an evidence ledger entry. An unsourced number is a defect, not a placeholder.
+- **Ask only what the user owns:** facts (product, price, budget, capacity, constraints) come from the user; analysis (market size, competitors, channels) comes from research. Never ask the user to do the analysis, and never use jargon in questions to the user.
+- **Framework conformance:** deliverables follow structures professionals recognize (SOSTAC, STP, SMART, KPI tree) — but a framework is a lens, not a form to fill. An empty section is declared, never padded.
+- **Internal consistency:** budget allocations sum, funnel math closes, every tactic serves an objective, every objective has a KPI. Checked mechanically, not rhetorically.
+- **Positioning must exclude:** a positioning statement that could describe any competitor is a defect. The swap test (replace our name with the top competitor's) must fail.
+- **Honesty about uncertainty:** assumptions are declared with ranges and confidence, never laundered into facts. A plan built on assumptions says so on page one.
+- **Measurability:** every tactic has a KPI, every objective a success signal, every plan explicit kill/scale criteria and a review cadence.
+- **Protect the Marketing Vision:** every downstream choice must serve a stated expected benefit or success signal; unauthorized scope is a vision divergence, not initiative.
+
+If a strategic choice looks obvious but you cannot trace it to evidence, research first.
+
+## Rule Zero: Triage
+
+Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
+
+| Level | Criteria | Required process |
+|---|---|---|
+| **E1 - Quick** | Single question or asset feedback: a positioning opinion, copy critique, one channel question | Answer directly. Numbers still need a source or an explicit "assumption" label. No new documents. |
+| **E2 - Campaign** | One campaign or one channel plan, bounded budget, existing strategy context | Mini-brief in the message (objective, audience, budget, KPI), targeted research, `mkt_docs/tactics/CAMPAIGN_[name].md`. Evidence ledger discipline applies. |
+| **E3 - Full Plan** | Complete marketing plan, go-to-market for a launch, entering a new market, or no prior strategy exists | Full workflow: all nine phases, all gates, full deliverable pack. |
+| **Research Spike** | Time-boxed market question that reduces uncertainty ("is there demand for X in market Y?") | Outcome in `mkt_docs/spikes/RESEARCH_[topic].md`. Ledger discipline applies. For strategy decisions, feed into E2/E3. |
+
+Cross-cutting rules:
+- Anything touching pricing strategy, brand repositioning, or a new market entry is never E1: those decisions cascade.
+- If a bigger scope emerges during E1/E2 work (e.g. the campaign reveals there is no positioning), stop, reclassify and declare it.
+- When in doubt, pick the higher level.
+- An E2 whose strategy context does not exist (no approved MKT-VISION or STRATEGY) escalates to E3: tactics without strategy is the failure mode this skill exists to prevent.
+
+## Operating Modes
+
+### Full Standalone
+
+Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
+
+Source of truth:
+- Vision: `mkt_docs/vision/MKT_VISION.md`, `principles.md`.
+- Evidence: `mkt_docs/research/evidence_ledger.md` + research documents in `mkt_docs/research/`.
+- Strategy artifacts: `mkt_docs/strategy/` (ICP_PERSONAS, THREAT_MAP, OBJECTIVES, STRATEGY).
+- Tactical artifacts: `mkt_docs/tactics/` (TACTICAL_PLAN, ACTION_90D, MEASUREMENT_PLAN).
+- Deliverables: `mkt_docs/deliverables/` (MARKETING_PLAN, ONE_PAGER, exports).
+- Spikes and handoff: `mkt_docs/spikes/`, `mkt_docs/audit/handoff.md`.
+
+Standalone mode is not reduced: it must handle full plans, campaigns, research spikes, reviews and closure without devPNT.
+
+### Hybrid in symbiosis with devPNT
+
+Use this mode when the `devpnt_*` tools are available and point at the current project.
+
+Authoritative hierarchy:
+1. **devPNT M-VISION**: strategic beacon of the plan cycle. Before strategy or tactics, read it and verify benefits, success signals, scope-in and non-goals.
+2. **devPNT Master Plan**: the marketing roadmap; milestones are plan cycles (a quarter, a launch, a market entry).
+3. **devPNT Action Plan**: the nine phases of the active engagement as tactical nodes.
+4. **devPNT governed artifacts**: the marketing artifact set (table below).
+5. **Local `mkt_docs/`**: readable context, Standalone fallback, evidence ledger home, shadow/mirror when useful.
+
+### Ownership matrix (the Hybrid seam)
+
+The skill owns the **process** (triage, phases, gates, lifecycle); devPNT owns the **machinery** (governed storage, versioned proposals, review wiring). The marketing artifacts occupy the same governance slots the software artifacts occupy in the sibling skill:
+
+| Artifact | Standalone master | Hybrid master (devPNT slot) | Mirror rule |
+|---|---|---|---|
+| Marketing vision | `vision/MKT_VISION.md` | M-VISION (`milestone_vision_<slug>`) | filesystem copy is a shadow; DB wins |
+| ICP & Personas | `strategy/ICP_PERSONAS.md` | `mkt_icp_personas` (D-UC slot) | shadow `SHADOW_[doc_key]_vX.Y.md` |
+| Threat map | `strategy/THREAT_MAP.md` | `mkt_threat_map` (P-TM slot) | shadow |
+| Objectives | `strategy/OBJECTIVES.md` | `mkt_objectives` | shadow |
+| Strategy | `strategy/STRATEGY.md` | `mkt_strategy` (E-ISP slot) | shadow, exported BEFORE tactics work |
+| Tactical plan | `tactics/TACTICAL_PLAN.md` | `mkt_tactical_plan` (E-TDD slot) | shadow, exported BEFORE action phase |
+| Measurement plan | `tactics/MEASUREMENT_PLAN.md` | `mkt_measurement_plan` (E-TP slot) | shadow |
+| Evidence ledger | `research/evidence_ledger.md` | `research/evidence_ledger.md` — **filesystem-first even in Hybrid** | validator needs it on disk; devPNT may reference, never copies |
+| Final plan + one-pager | `deliverables/` | assembled from ACCEPTED artifact versions | PDF via `devpnt_generate_document_pdf` when available |
+| Handoff | `audit/handoff.md` | `audit/handoff.md` | always filesystem |
+
+Hybrid rules:
+- devPNT is the governed source for plans and strategy artifacts; do not create a second truth in `mkt_docs/`.
+- The skill stays autonomous: if devPNT is not there, switch to Standalone without losing capability.
+- If the user request, the local vision and the M-VISION diverge, stop and make the conflict explicit.
+- Never auto-accept devPNT proposals: present the preview and wait for explicit confirmation.
+- Where the local devPNT protocol imposes stricter gates (vision creation/amendment gates, independent review gates), follow them: they are the same discipline this skill encodes.
+
+## The Three Engineered Guarantees
+
+Every E3 (and every E2 with numbers) is bound by these. They are the product; the phases below exist to feed them.
+
+1. **Evidence ledger** (`research.md`): every number is classified — `FACT` (user input or primary data), `BENCHMARK` (external source, URL + date mandatory), `ASSUMPTION` (declared, range + confidence mandatory) — and referenced as `[EV-nn]` wherever used. `mkt_check.py ledger` fails on unresolved references and unsourced benchmarks.
+2. **Mechanical validation** (`mkt_check.py`): `budget` (allocations sum to the declared total), `funnel` (spend → clicks → leads → customers chain recomputed, ±5% tolerance, compared to the objective target), `trace` (every tactic names an objective; every objective has a KPI in the measurement plan). A plan that fails validation is not presented to the user as finished.
+3. **Adversarial CMO review** (`review.md`): before the strategy gate and before final packaging, an independent fresh-context reviewer attacks the artifact — swap test on positioning, untraced numbers, orphan tactics, missing kill criteria. Findings are answered one by one; cap 3 rounds, then surface open findings to the user.
+
+## E3 Workflow (nine phases on the SOSTAC spine)
+
+Deliverable language: ask for (or infer) the target market's language in Discovery; artifacts and deliverables are written in it. The skill's internal doctrine stays English.
+
+### 1. Intake & Triage
+- Declare the level. Read `mkt_docs/audit/handoff.md` and `mkt_docs/README.md`/`INDEX.md` if they exist; if handoff dates are inconsistent, treat it as history.
+- Hybrid: bootstrap devPNT, restore Master/Action Plan and any existing marketing artifacts before asking the user anything they already answered.
+
+### 2. Discovery (Situation — internal)
+- Run elicitation **Wave 1** (`elicitation.md`): business facts only, plain language, max 4 questions per round, options where a real choice exists.
+- Every fact captured becomes a `FACT` ledger entry. Draft `MKT_VISION.md` (Status: DRAFT) from the answers.
+- **Vision Gate:** the user approves the MKT-VISION (expected benefit, success signals, non-goals) before research spends effort. Hybrid: this is the devPNT M-VISION creation gate — vision first, then the milestone.
+
+### 3. Research (Situation — external)
+- Follow `research.md`. Prefer the deep-research skill as the engine when available; fallback to the manual playbook.
+- Mandatory sweeps: market sizing (bottom-up preferred), competitor scan, voice-of-customer mining, channel benchmarks. Every number lands in the ledger with source + date.
+- Two independent sources for any number that will drive a budget decision.
+
+### 4. Situation Analysis
+- Synthesize research into `ICP_PERSONAS.md` (every persona trait traces to VoC evidence) and `THREAT_MAP.md` (competitor moves, risks, mitigations).
+- SWOT built from ledger entries, not adjectives. PESTEL / Five Forces only when the market warrants them (`frameworks.md` says when).
+
+### 5. Objectives — **USER GATE**
+- Run elicitation **Wave 2** (ambition, trade-offs, risk appetite, timeline).
+- Draft `OBJECTIVES.md`: SMART objectives (`O1`, `O2`, ...) + KPI tree. Each objective cites the ledger entries that make it plausible.
+- The user approves objectives before strategy. Objectives the user did not set are proposals, and say so.
+
+### 6. Strategy — **REVIEW + USER GATE**
+- Draft `STRATEGY.md`: segmentation, targeting choice with rationale, positioning (Dunford components + statement), messaging house.
+- **Adversarial review** (`review.md`) before the user sees it. Fix or answer every finding.
+- The user approves the strategy. Hybrid: propose as governed doc, user accepts in devPNT.
+
+### 7. Tactics — **VALIDATOR GATE**
+- Run elicitation **Wave 3** (execution capacity: who writes, who runs ads, tooling, sales follow-up).
+- Draft `TACTICAL_PLAN.md`: channel table (channel | objective served | KPI | budget | owner), budget allocation, funnel model per acquisition channel.
+- `mkt_check.py budget && mkt_check.py funnel && mkt_check.py trace` must pass. A tactic that serves no objective is deleted or the objective set is revisited — never silently kept.
+
+### 8. Action
+- Draft `ACTION_90D.md`: sequenced 90-day plan (what starts when, owner, dependency), first 2 weeks day-level, rest weekly.
+
+### 9. Control & Packaging — **FINAL REVIEW GATE**
+- Draft `MEASUREMENT_PLAN.md`: KPI tree with targets and benchmark references, review cadence, explicit kill/scale criteria per channel.
+- Assemble `MARKETING_PLAN.md` (the SOSTAC deliverable) and `ONE_PAGER.md` from the approved artifacts — assembly, not rewriting; on divergence the approved artifact wins.
+- Final adversarial review on the assembled plan + `mkt_check.py check` CLEAN.
+- Offer exports: PDF, slide deck, budget spreadsheet (use the client's document skills when available).
+- Update `handoff.md`. Hybrid: mark plan nodes DONE only after the user accepts the final artifacts.
+
+## E2 Workflow (campaign)
+
+A bounded version of the same discipline: mini-brief (objective, audience, budget, KPI — from an approved strategy context) → targeted research (channel benchmarks for the chosen channel, ledger discipline) → `CAMPAIGN_[name].md` with budget + funnel tables (validator: `budget`, `funnel`) → measurement section with kill/scale criteria. No E2 without strategy context: escalate to E3 instead.
+
+## mkt_docs documents: indexes + lifecycle
+
+- **`mkt_docs/README.md` (curated, by hand):** reading priority, few lines.
+- **`mkt_docs/INDEX.md` (generated, `mkt_check.py index`):** manifest of every canonical doc (`vision/`, `strategy/`, `tactics/`, `deliverables/`) with description and status. Never by hand.
+- `research/`, `spikes/`, `audit/` are discovery-by-grep: they do not enter the manifest. Research freshness is carried by ledger dates, not by the manifest.
+
+Every canonical document opens with frontmatter:
+
+```markdown
+---
+description: One line — what it is and when to read it.
+status: CURRENT              # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
+supersedes: old_doc.md       # only if it replaces another doc
+---
+```
+
+`Status: DRAFT` informs; `Status: APPROVED` (inside MKT_VISION/OBJECTIVES/STRATEGY bodies, granted only by the user) binds. A superseded doc stays as history with `status: SUPERSEDED`. Missing `status` = warning in `validate`.
+
+## Deliverable quality bar
+
+The final plan must be recognizable by a marketing professional:
+- SOSTAC section structure, executive summary first.
+- Every number carries `[EV-nn]`; the ledger ships as an appendix.
+- Assumptions section on page one when material assumptions exist.
+- Positioning passes the swap test; messaging house has proof points, not slogans.
+- Budget table, funnel model, 90-day plan and kill/scale criteria present — a plan without a control loop is a brochure.
+
+## Mechanical Enforcement
+
+The prompt is not enforcement. When the project needs repeatable guarantees:
+- read `ENFORCEMENT.md`;
+- use `scripts/mkt_check.py validate --strict` in CI;
+- run `scripts/mkt_check.py check` before declaring any E2/E3 deliverable done.
+
+The validator is a support, not a universal prerequisite: the skill must stay usable in environments without Python, declaring what it cannot verify automatically.

package/skills/mkt-agentic-sdlc/elicitation.md

@@ -0,0 +1,89 @@
+# Elicitation — question waves
+
+The cardinal rule: **ask only what the user uniquely owns.** Facts about their
+business come from them; everything derivable from research comes from
+research. Asking the user "who are your competitors and how are you
+positioned?" is outsourcing the skill's own job — the failure mode this file
+exists to prevent.
+
+Question style (all waves):
+- Plain language, zero marketing jargon. Not "what's your ICP?" but "describe
+  your best current customer".
+- Max 4 questions per round; multiple rounds per wave allowed but each round
+  must be worth the interruption.
+- Offer concrete options where a real choice exists (narrows the reply,
+  speeds the round). Use the client's structured-question facility when
+  available.
+- **Pre-authorize "I don't know" on numeric asks.** When you ask for a figure
+  the client may never have measured (conversion rate, CAC, open rate),
+  append the permission in the question itself — "...ma se non l'avete mai
+  misurato, va bene 'non lo so'." It removes the pressure to invent a number
+  and keeps the ledger honest (an unmeasured figure becomes a researched
+  BENCHMARK or a declared ASSUMPTION, never a fabricated FACT).
+- Every answer that is a fact becomes a `FACT` entry in the evidence ledger,
+  same discipline as researched numbers.
+- **Seeds are allowed, analysis is not:** "which competitors do you lose
+  deals to?" is a fact the user owns (their perceived competitive set) and a
+  legitimate research seed. "What are their strengths and weaknesses?" is
+  analysis — forbidden to ask, mandatory to research.
+
+## Wave 1 — Discovery (phase 2, before any research)
+
+Cover, across rounds:
+1. **Offer** — what they sell, in their words; what problem it solves.
+2. **Price & margin** — price point(s), rough margin, discount reality.
+3. **Current traction** — customers today (how many, what kind), revenue
+   order of magnitude, where the current customers came from.
+4. **Market & language** — geography, target market, language for the
+   deliverables.
+5. **Budget & horizon** — marketing budget range (a range is fine), planning
+   horizon (quarter / year / launch window).
+6. **Team & capacity** — who will execute marketing (nobody / founder /
+   person / team / agency), hours realistically available.
+7. **Sales motion** — how a sale happens today (self-serve, demo calls,
+   proposals, retail...), typical cycle length.
+8. **Existing assets** — website, mailing list, social accounts and their
+   real state; brand materials.
+9. **Constraints** — legal/regulatory limits, channels they refuse, brand
+   red lines.
+10. **Competitor seeds** — who they lose deals to / who customers compare
+    them with (seed, not analysis).
+
+Skip path: any item already answered by an approved MKT-VISION or earlier
+session record is not re-asked — note where the answer came from.
+
+## Wave 2 — Ambition (phase 5 entry, after research)
+
+Now the user chooses with research on the table. Present the relevant
+evidence first (one short paragraph), then ask:
+1. **Growth vs margin** — push volume or protect profitability?
+2. **Risk appetite** — proven channels only, or reserve an experimental slice?
+3. **Timeline pressure** — is there a hard date (launch, season, runway)?
+4. **Non-negotiables** — anything the objectives must include or avoid?
+
+## Wave 3 — Execution capacity (phase 7 entry)
+
+1. **Content capacity** — who writes/records, in which language, how often
+   realistically?
+2. **Paid capacity** — who runs ads; any platform experience in-house?
+3. **Follow-up capacity** — if leads double, who answers them? CRM/tooling?
+4. **Budget flexibility** — is the budget fixed or scalable if a channel
+   proves itself?
+
+## Reflect
+
+Fold answers into the artifacts (MKT_VISION, OBJECTIVES, TACTICAL_PLAN) and
+the ledger — never leave them only in chat. The written document is what the
+next session and the reviewer read.
+
+## Anti-patterns
+
+- **Outsourcing analysis**: asking the user for market size, competitor
+  strengths, channel choice, or positioning. That is the skill's work.
+- **Jargon**: ICP, CAC, SOM, funnel — translate or don't ask.
+- **Interrogation**: more than 4 questions per round, or drip-feeding across
+  many turns instead of structured rounds.
+- **Re-asking the recorded**: anything an approved vision or ledger FACT
+  already answers.
+- **Collecting without folding in**: answers that never reach a document or
+  the ledger are lost to the next session.

package/skills/mkt-agentic-sdlc/frameworks.md

@@ -0,0 +1,105 @@
+# Framework Selection Guide
+
+A framework is a lens, not a form. Pick per relevance; an empty section is
+declared ("Five Forces skipped: single-competitor niche, structure analysis
+adds nothing"), never padded. A deliverable stuffed with every framework is a
+student essay, not a plan.
+
+## The spine: SOSTAC
+
+The plan's section structure is always SOSTAC (PR Smith) — the skeleton
+professionals recognize:
+
+| SOSTAC | Phase(s) | Output |
+|---|---|---|
+| **S**ituation | 2-4 (Discovery, Research, Situation Analysis) | where we are: market, competitors, customers, own assets |
+| **O**bjectives | 5 | where we want to be: SMART + KPI tree |
+| **S**trategy | 6 | how we get there at altitude: STP, positioning, messaging |
+| **T**actics | 7 | with which instruments: channels, budget, funnel |
+| **A**ction | 8 | who does what when: 90-day plan |
+| **C**ontrol | 9 | how we know it works: measurement, kill/scale |
+
+## Situation-phase lenses (pick, don't stack)
+
+| Lens | Use when | Skip when |
+|---|---|---|
+| **SWOT** | always — the synthesis container for research findings | never skipped, but every cell must cite `[EV-nn]` entries; adjectives without evidence are deleted |
+| **PESTEL** | regulated markets, macro-exposed sectors (energy, health, finance), international expansion | stable domestic niche — declare the skip |
+| **Porter Five Forces** | entering a new market or industry-structure questions (margins, supplier power) | plan for an existing position in a known market |
+| **TAM/SAM/SOM** | always for E3 | — (method rules below) |
+
+**Market sizing rules:** bottom-up preferred (number of reachable potential
+customers × realistic price point, from ledger entries); top-down (industry
+report % slicing) only as a cross-check. A TAM that exists only top-down is a
+`WARN` in review. SOM must be defendable from channel capacity, not ambition.
+
+## Customer lenses
+
+- **ICP (Ideal Customer Profile):** firmographic/demographic criteria table —
+  who we sell to and, as important, who we do NOT sell to.
+- **Personas + JTBD:** at most 2-3 personas, each built from voice-of-customer
+  evidence (mined reviews, forums, support threads — see `research.md`). Each
+  persona carries: job-to-be-done, buying trigger, top objections, watering
+  holes (where they actually are). A persona trait with no VoC evidence is an
+  ASSUMPTION and is labeled as one; an invented persona is a review finding.
+
+## Strategy lenses
+
+- **STP:** Segmentation (from research) → Targeting (a CHOICE, with rationale
+  and explicit rejections: "segment B rejected because...") → Positioning.
+- **Positioning (April Dunford components):** competitive alternatives (what
+  the customer does today, including "nothing"), unique attributes, value
+  (evidence-backed), best-fit segment, market category. Then the statement:
+
+  > For [segment] who [need], [name] is the [category] that [unique value],
+  > unlike [main alternative] which [limitation].
+
+  **Swap test (mandatory):** replace [name] with the top competitor. If the
+  statement still holds, the positioning does not exclude and FAILS.
+- **Messaging house:** roof = value proposition (one sentence), pillars = 2-4
+  messages, foundation = proof points per pillar. A pillar without proof
+  points is a slogan; the review flags it.
+
+## Objectives
+
+- **SMART**, each objective `O1`, `O2`, ... with owner-visible target and date.
+- **KPI tree:** north-star metric → driver metrics → channel KPIs. Every
+  objective maps into the tree; every channel KPI rolls up. The tree lives in
+  `MEASUREMENT_PLAN.md`; `mkt_check.py trace` verifies the chain.
+- 3-5 objectives maximum. Ten objectives = no objectives.
+
+## Tactics lenses
+
+- **Funnel model:** AARRR (acquisition, activation, retention, referral,
+  revenue) for product-led; classic lead funnel (traffic → lead → MQL → SQL →
+  customer) for sales-led. Pick per the sales motion captured in Discovery.
+  Funnel rows must recompute (`mkt_check.py funnel`).
+- **Sales-led / B2B funnel (important — the funnel table is shaped for
+  immediate-purchase e-commerce).** In a long-cycle B2B motion the monthly
+  funnel output is a **qualified lead / demo**, NOT a closed customer — today's
+  lead closes in 3-5 months. So: (a) put ONLY the paid click channels in the
+  `Funnel Model` table, and read its `Customers` column as *qualified
+  demos/leads* and `CAC` as *cost per qualified demo* — state the relabel
+  explicitly; (b) the primary sales-led motions (referral, content, outbound)
+  are NOT click funnels — represent their yield in a separate **Pipeline
+  build-up table** (per-source qualified leads/month vs the objective target);
+  (c) model the multi-stage sales funnel (MQL→SQL→demo→POC→won) and the
+  closed-won LAG in that pipeline section, not in the click-funnel table.
+  Forcing closed customers into a monthly click-funnel produces absurd CAC.
+- **Channel selection matrix:** score candidate channels on ICP presence
+  (from VoC watering holes), intent level, benchmark cost `[EV-nn]`, and
+  execution capacity (from Wave 3). Choose few: 2-3 core channels beat 8
+  half-run ones. A channel chosen against the matrix needs written rationale.
+- **Budget heuristics:** 70/20/10 (core / adjacent / experimental) as the
+  default split; deviations argued. Industry %-of-revenue norms are
+  BENCHMARKS — they enter only with a sourced ledger entry, never from memory.
+- **4P/7P:** use as a completeness checklist on the tactical plan (price,
+  place and product decisions the plan silently makes), not as a section.
+
+## Control
+
+- Review cadence: weekly channel KPIs, monthly objective review, quarterly
+  strategy review.
+- **Kill/scale criteria per channel, set BEFORE launch:** "kill if CAC > X
+  after spend Y; scale if CAC < Z at volume W" — thresholds justified by
+  ledger benchmarks. A plan without kill criteria is a brochure (review BLOCK).

package/skills/mkt-agentic-sdlc/research.md

@@ -0,0 +1,104 @@
+# Research Playbook + Evidence Ledger Discipline
+
+Research turns the user's facts into a defendable picture of the outside
+world. Its output is never prose alone: every number lands in the ledger,
+every claim carries its reference.
+
+## The Evidence Ledger
+
+Single file: `mkt_docs/research/evidence_ledger.md`. One table, one row per
+piece of evidence:
+
+| ID | Claim | Class | Value / Range | Source | Date | Confidence |
+|---|---|---|---|---|---|---|
+
+- **ID**: `EV-01`, `EV-02`, ... sequential, never reused. Artifacts cite
+  numbers as `[EV-nn]`.
+- **Class** (exactly one):
+  - `FACT` — user input or primary data (their analytics, their CRM export).
+    Source = "user, Wave 1" or the data file.
+  - `BENCHMARK` — external number. Source URL **and** publication date
+    mandatory. The Source cell must carry the actual external URL, NOT a
+    pointer to one of your own research documents that aggregates it ("see
+    VOC.md" is not a source — the validator rejects a BENCHMARK whose Source
+    has no `http`). A benchmark older than 24 months is flagged in review.
+  - `ASSUMPTION` — a number we need but could not source. Range mandatory
+    (not a point estimate), Confidence mandatory (HIGH/MED/LOW), and the
+    rationale in the Claim cell. Assumptions that drive budget decisions are
+    listed in the plan's page-one Assumptions section.
+- **Laundering is the cardinal sin:** an ASSUMPTION never migrates to
+  BENCHMARK without a real source; a stale benchmark is not refreshed by
+  editing its date. `mkt_check.py ledger` enforces the mechanical part
+  (references resolve, benchmarks have URLs, assumptions have confidence);
+  honesty enforces the rest.
+
+**Two-source rule:** any number that will drive a budget allocation or an
+objective target needs two independent sources (two ledger rows or one row
+citing both). One vendor's blog post does not size a market.
+
+**Source hierarchy** (prefer higher): primary data > official statistics /
+regulator data > industry analyst reports > trade press > vendor benchmarks >
+individual blog posts (last resort, flag as weak in Confidence).
+
+## The engine
+
+**Preferred:** when the `deep-research` skill (or an equivalent multi-agent
+research harness) is available, use it as the engine — one refined question
+per sweep, findings adversarially verified, sources cited. Feed its cited
+findings into the ledger; do not bypass the ledger because the engine already
+cites.
+
+**Fallback:** manual web search per the sweep playbooks below. Slower;
+the ledger discipline is identical.
+
+## Mandatory sweeps (E3)
+
+### 1. Market sizing
+- Bottom-up first: reachable potential customers (from official statistics,
+  association registries, platform audience tools) × realistic price
+  `[EV: price FACT]`. Top-down (report % slicing) only as cross-check.
+- Output: TAM/SAM/SOM with every input as a ledger row.
+
+### 2. Competitor scan
+- Start from the user's seeds (Wave 1) + search-discovered players.
+- Per competitor: positioning claim (their own words, from their site),
+  visible pricing, observed channels (where do they show up: ads
+  transparency libraries, social presence, SEO footprint), review sentiment.
+- Output: `mkt_docs/research/COMPETITORS.md` + ledger rows for anything
+  numeric. Observed facts, not speculation about their strategy.
+
+### 3. Voice of customer (VoC)
+- Mine reviews (their category on G2/Capterra/Trustpilot/Amazon/app stores as
+  applicable), forums, Reddit, comment sections — where the target segment
+  already speaks.
+- Harvest verbatim quotes with URLs: pains, desired outcomes, objections,
+  vocabulary (the actual words become messaging raw material).
+- Output: `mkt_docs/research/VOC.md`. Persona traits in `ICP_PERSONAS.md`
+  must trace here.
+
+### 4. Channel benchmarks
+- For candidate channels: typical CPC/CPM, CTR, conversion rates, CAC ranges
+  for the industry — each a BENCHMARK row with URL + date.
+- These feed the funnel model; without them the funnel is fiction.
+
+### Optional sweeps
+- Trends/seasonality (search-volume tools, industry calendars) when timing
+  matters; regulatory scan when PESTEL is in play.
+
+## Research spikes
+
+A standalone market question outside a full engagement:
+`mkt_docs/spikes/RESEARCH_[topic].md` — question, time-box, method, answer,
+ledger rows created, consequences. Max 1 page + ledger entries.
+
+## Anti-patterns
+
+- **Numbers from memory:** model knowledge is not a source. If it matters,
+  search it; if unsearchable, it is an ASSUMPTION with a range.
+- **Single-source budget decisions** (violates the two-source rule).
+- **Prose-only research:** findings that never become ledger rows are lost
+  and unverifiable.
+- **Competitor mind-reading:** report what is observable; label inference as
+  inference.
+- **Benchmark hoarding:** 50 ledger rows nobody cites. Research serves the
+  plan; unreferenced rows get pruned at closure (validator warns).

package/skills/mkt-agentic-sdlc/review.md

@@ -0,0 +1,73 @@
+# CMO Review Discipline
+
+Applies at the Strategy gate (phase 6), the final packaging gate (phase 9),
+and any independent review slot in a connected governance layer (devPNT
+review gates). This is the single definition of how to request, receive, and
+perform a marketing review; other places point here instead of restating it.
+
+The reviewer is a skeptical CMO with a fresh context: different session or
+subagent, read-only, given the artifacts — never "review my session".
+Fallback when no independent context is available: run the battery yourself
+as an explicit, separate adversarial pass, and say so (independence is
+reduced).
+
+## Requesting
+
+Hand the reviewer:
+- **Scope**: which artifact, which gate, in one or two lines.
+- **The artifact itself** — full text, not a paraphrase.
+- **The constraints it derives from**: the approved MKT-VISION, the
+  OBJECTIVES (for strategy/tactics reviews), the ICP_PERSONAS and THREAT_MAP,
+  and the **evidence ledger** — the reviewer checks the artifact **against**
+  them, not only for internal consistency.
+- Which finding classes to cover when the default is not obvious.
+
+## Receiving
+
+**Answer findings one by one — fix, or justify with evidence.** Silent drops
+turn review into theater. Disagree explicitly with reasoning; never resolve a
+disagreement by rewording the finding. Cap 3 rounds; then surface open
+findings to the user rather than looping. If any edit is made after a PASS,
+re-review: reviewed text must equal shipped text.
+
+## Reviewing — the red-flag battery
+
+Severity: `BLOCK` (artifact does not pass the gate) / `WARN` (ships only with
+explicit user acknowledgment). Every finding cites its location.
+
+| # | Check | Severity |
+|---|---|---|
+| R1 | **Swap test**: replace our name with the top competitor in the positioning STATEMENT ACTUALLY PUBLISHED (not a stronger paraphrase — test the exact sentence that ships); if it still holds for any competitor, positioning does not exclude | BLOCK |
+| R2 | **Untraced number**: any figure without `[EV-nn]` | BLOCK |
+| R3 | **Laundered assumption**: ASSUMPTION used as certainty in prose ("the market is worth X" vs "we assume X-Y") | BLOCK |
+| R4 | **Orphan tactic**: tactic serving no objective; **orphan objective**: objective with no KPI or no serving tactic | BLOCK |
+| R5 | **Broken funnel math**: chain does not recompute, or projected outcome does not meet the objective target and no gap is declared | BLOCK |
+| R6 | **Missing kill/scale criteria** on any funded channel | BLOCK |
+| R7 | **Stale benchmark**: >24 months old, not flagged | WARN |
+| R8 | **Top-down-only TAM**: no bottom-up cross-check | WARN |
+| R9 | **Invented persona**: persona trait with no VoC trace and no ASSUMPTION label | WARN |
+| R10 | **Channel vs ICP mismatch**: channel scores poorly on the selection matrix with no written rationale | WARN |
+| R11 | **Generic messaging**: pillar without proof points; value prop interchangeable with any competitor's | WARN |
+| R11b | **Low-cost trap / price-led positioning**: the positioning leads with cheapness ("prezzo onesto", "senza pagarlo caro", price comparison as the hook) instead of leading with value and framing price as a consequence — invites the customer to leave for the next cheaper option | WARN (BLOCK if the whole prop reduces to price) |
+| R12 | **Vision divergence**: artifact pursues a goal absent from the approved MKT-VISION, or violates a non-goal | BLOCK |
+| R13 | **Capacity fiction**: plan requires execution capacity Wave 3 says does not exist | BLOCK |
+| R14 | **SMART violation**: objective without number, date, or owner | WARN |
+| R15 | **Strawman swap-test**: the swap-test verdict tests a differentiated formulation while a WEAKER, generic sentence is what actually ships as the positioning line | BLOCK |
+
+## Conformance statement (strategy & final-plan reviews)
+
+A PASS is **not valid on "found nothing"**. The verdict must map each
+constraint to evidence: every approved objective → the strategy element
+serving it → the tactics funding it → the KPI measuring it (cite sections);
+every MKT-VISION benefit and non-goal → where the artifact honors it; every
+material ledger ASSUMPTION → where the plan declares it. A gap in the chain
+is a finding, not a footnote. Quick E1/E2 reviews stay findings-only.
+
+## Anti-patterns
+
+- **Praise padding** — a review reports problems and fixes.
+- **Batch-dismissal** of a findings list with one blanket reply.
+- **Severity inflation/deflation** — a style preference is not a BLOCK; a
+  broken funnel is not a nit.
+- **Scope-creep findings** — issues outside the artifact under review are
+  filed separately, not mixed in.