@antoneeo/mkt-agentic-sdlc-skill 0.2.1 → 0.3.1

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

@@ -1,89 +1,147 @@
-# 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.
+# Elicitation — question waves
+
+`## The question discipline` below governs EVERY question to the user — any
+phase, any level, inside or outside the waves. The waves are the only place the
+process *plans* the cost of asking.
+
+Ask for the **benefit** the user wants, never for the mechanism they imagine delivers it: a mechanism stated as a requirement forecloses every better one.
+
+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.
+
+## The question discipline
+
+A question outside the waves is legal only when BOTH hold:
+
+1. **Searched first, and the search is named — with its result.** The answer is
+   not on record (MKT-VISION, ledger, session notes) and not derivable from
+   research — and the question states what you searched or researched **and what
+   it returned**. **Never fake the search**: "I looked and found nothing" that
+   names no sources and no queries is a search not run. A question research can
+   answer is research outsourced to the client — the cardinal rule's own
+   failure mode, restated as a legality test.
+2. **It names what is blocked.** The question states the decision or fact that
+   cannot be resolved without the reply — what changes in the plan depending on
+   the answer. If nothing downstream changes, there is no question.
+
+Never legal:
+
+- **Generic confirmation** — "shall I proceed?", "is the plan OK so far?". The
+  gates are where approval lives; if a real risk motivates the ask, name the
+  risk and the fork — that is a blocking question and carries the form below.
+- **Preference-fishing** — asking the client to pick among options equivalent
+  in their effect on the objective. Cheapness to undo is NOT the test.
+- **Re-asking the record** — anything an approved MKT-VISION, a ledger entry
+  or an earlier answer already states.
+
+**Precedence:** a choice the user uniquely owns (budget, risk appetite,
+non-negotiables, brand red lines, approvals the gates reserve) is never
+preference-fishing; the list above reaches choices that are *not* theirs.
+
+**Default non-blocking.** An unknown on which no fork of the plan depends:
+record it as a ledger **ASSUMPTION** — the native mechanism this lens already
+has — proceed, and present the open points **batched** with the next wave or
+the deliverable, answered by exception. Same evidence duty as a question: each
+assumption states **what it is taken from** (a benchmark, a comparable, a
+stated policy) and **the alternative it excludes**, and every assumption
+reaches the batch — an assumption nobody is shown is a silent decision, and an
+unshown ASSUMPTION row is exactly a fabricated FACT waiting to happen.
+
+**Blocking is reserved** for three cases: proceeding under ANY assumption would
+waste the work (the forks diverge at once); the decision is one the user
+uniquely owns; or the doctrine itself mandates the stop. One mandating file
+prescribes its own hand-over, and there this form does not apply:
+`review.md`'s round cap (the artifact plus the open findings). That list is closed.
+Every other blocking question carries the form:
+
+- the fork: the concrete options and what each implies for the plan;
+- the evidence: what you researched and what it leaves undecided;
+- why no assumption survives — what work is discarded if you assume and are
+  wrong;
+- why it is the user's call;
+- what stays blocked until answered.
+
+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

@@ -1,105 +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).
+# 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).