@antoneeo/mkt-agentic-sdlc-skill 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/gemini-extension.json +6 -6
  3. package/package.json +50 -50
  4. package/skills/mkt-agentic-sdlc/SKILL.md +240 -240
  5. package/skills/mkt-agentic-sdlc/review.md +51 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.8.0] - 2026-09-01
4
+
5
+ Spine-only release: `review.md` updated byte-identical across the family
6
+ (authored in the code lens, F-045 / code 1.30.0).
7
+
8
+ ### Added
9
+ - **Review-loop convergence (shared spine `review.md`).** *Revise means
10
+ converge, not accrete*: lean rewrite at the latest before round 3, revision
11
+ archaeology lives in REVIEW_LOG, never in the artifact. *Severity contract*
12
+ stated with every review request: blocker = unfit-to-proceed evidence only,
13
+ wishes are WARN at most. *Scripted author pre-audit*: resolve every anchor
14
+ and recount every count before requesting. The new *behavioural-claim-probes*
15
+ reviewer clause is lens-gated and self-disarmed in this lens (this SKILL.md
16
+ defines no Execute-Before-Specify duty).
17
+
3
18
  ## [0.7.0] - 2026-08-28
4
19
 
5
20
  Spine + overlay delta parked for the next release of this lens (shipped first
package/gemini-extension.json CHANGED
@@ -1,6 +1,6 @@
1
- {
2
- "name": "mkt-agentic-sdlc",
3
- "version": "0.7.0",
4
- "description": "Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger and optional devPNT integration.",
5
- "author": "Antonio Pinto (https://github.com/Antoneeo)"
6
- }
1
+ {
2
+ "name": "mkt-agentic-sdlc",
3
+ "version": "0.8.0",
4
+ "description": "Evidence-First marketing planning protocol with engagement triage, SOSTAC workflow, evidence ledger and optional devPNT integration.",
5
+ "author": "Antonio Pinto (https://github.com/Antoneeo)"
6
+ }
package/package.json CHANGED
@@ -1,50 +1,50 @@
1
- {
2
- "name": "@antoneeo/mkt-agentic-sdlc-skill",
3
- "version": "0.7.0",
4
- "description": "Evidence-First marketing planning protocol for Claude Code, Gemini CLI, Google Antigravity and Codex: engagement triage, SOSTAC workflow, evidence ledger, mechanical validator and optional devPNT integration.",
5
- "keywords": [
6
- "claude-code",
7
- "claude-skill",
8
- "gemini-cli",
9
- "skill",
10
- "marketing",
11
- "marketing-plan",
12
- "sostac",
13
- "ai-agent"
14
- ],
15
- "author": "Antonio Pinto (https://github.com/Antoneeo)",
16
- "license": "MIT",
17
- "publishConfig": {
18
- "access": "public"
19
- },
20
- "bin": {
21
- "mkt-sdlc-init": "scripts/init.js",
22
- "mkt-sdlc-install-skill": "scripts/postinstall.js"
23
- },
24
- "scripts": {
25
- "postinstall": "node scripts/postinstall.js",
26
- "preuninstall": "node scripts/preuninstall.js"
27
- },
28
- "files": [
29
- "skills/mkt-agentic-sdlc/SKILL.md",
30
- "skills/mkt-agentic-sdlc/frameworks.md",
31
- "skills/mkt-agentic-sdlc/elicitation.md",
32
- "skills/mkt-agentic-sdlc/research.md",
33
- "skills/mkt-agentic-sdlc/templates.md",
34
- "skills/mkt-agentic-sdlc/review.md",
35
- "skills/mkt-agentic-sdlc/scripts/sdlc_core.py",
36
- "skills/mkt-agentic-sdlc/routing.md",
37
- "skills/mkt-agentic-sdlc/guides.md",
38
- "skills/mkt-agentic-sdlc/vision.md",
39
- "skills/mkt-agentic-sdlc/dispatch.md",
40
- "skills/mkt-agentic-sdlc/ENFORCEMENT.md",
41
- "skills/mkt-agentic-sdlc/scripts/mkt_check.py",
42
- "gemini-extension.json",
43
- "README.md",
44
- "CHANGELOG.md",
45
- "scripts/lib.js",
46
- "scripts/init.js",
47
- "scripts/postinstall.js",
48
- "scripts/preuninstall.js"
49
- ]
50
- }
1
+ {
2
+ "name": "@antoneeo/mkt-agentic-sdlc-skill",
3
+ "version": "0.8.0",
4
+ "description": "Evidence-First marketing planning protocol for Claude Code, Gemini CLI, Google Antigravity and Codex: engagement triage, SOSTAC workflow, evidence ledger, mechanical validator and optional devPNT integration.",
5
+ "keywords": [
6
+ "claude-code",
7
+ "claude-skill",
8
+ "gemini-cli",
9
+ "skill",
10
+ "marketing",
11
+ "marketing-plan",
12
+ "sostac",
13
+ "ai-agent"
14
+ ],
15
+ "author": "Antonio Pinto (https://github.com/Antoneeo)",
16
+ "license": "MIT",
17
+ "publishConfig": {
18
+ "access": "public"
19
+ },
20
+ "bin": {
21
+ "mkt-sdlc-init": "scripts/init.js",
22
+ "mkt-sdlc-install-skill": "scripts/postinstall.js"
23
+ },
24
+ "scripts": {
25
+ "postinstall": "node scripts/postinstall.js",
26
+ "preuninstall": "node scripts/preuninstall.js"
27
+ },
28
+ "files": [
29
+ "skills/mkt-agentic-sdlc/SKILL.md",
30
+ "skills/mkt-agentic-sdlc/frameworks.md",
31
+ "skills/mkt-agentic-sdlc/elicitation.md",
32
+ "skills/mkt-agentic-sdlc/research.md",
33
+ "skills/mkt-agentic-sdlc/templates.md",
34
+ "skills/mkt-agentic-sdlc/review.md",
35
+ "skills/mkt-agentic-sdlc/scripts/sdlc_core.py",
36
+ "skills/mkt-agentic-sdlc/routing.md",
37
+ "skills/mkt-agentic-sdlc/guides.md",
38
+ "skills/mkt-agentic-sdlc/vision.md",
39
+ "skills/mkt-agentic-sdlc/dispatch.md",
40
+ "skills/mkt-agentic-sdlc/ENFORCEMENT.md",
41
+ "skills/mkt-agentic-sdlc/scripts/mkt_check.py",
42
+ "gemini-extension.json",
43
+ "README.md",
44
+ "CHANGELOG.md",
45
+ "scripts/lib.js",
46
+ "scripts/init.js",
47
+ "scripts/postinstall.js",
48
+ "scripts/preuninstall.js"
49
+ ]
50
+ }
package/skills/mkt-agentic-sdlc/SKILL.md CHANGED
@@ -1,240 +1,240 @@
1
- ---
2
- name: mkt-agentic-sdlc
3
- version: 0.7.0
4
- 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.
5
- author: Antonio Pinto (https://github.com/Antoneeo)
6
- copyright: (c) 2026 Antonio Pinto
7
- ---
8
-
9
- # Marketing Agentic SDLC
10
-
11
- 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.
12
-
13
- Support files in the skill directory:
14
- - `frameworks.md`: which professional framework to use in which phase (SOSTAC, STP, JTBD, positioning, KPI tree) — and when NOT to use one.
15
- - `elicitation.md`: the question waves and the only-facts-you-own rule.
16
- - `research.md`: the research playbook and the evidence ledger discipline.
17
- - `templates.md`: templates for every artifact and deliverable.
18
- - `review.md`: the family's shared review discipline (independence ladder, rounds, log). The marketing-specific attack surface — swap test, untraced numbers, orphan tactics, missing kill/scale — lives in `frameworks.md`'s falsification rules; the adversarial CMO review applies them through `review.md`'s procedure.
19
- - `scripts/mkt_check.py` + `scripts/sdlc_core.py`: the mechanical validator (`check`, `validate`, `ledger`, `budget`, `funnel`, `trace`, `index`, plus the spine's `stale`/`mark`/`gate`/`orient`/`plan`/`migrate`). Two files: the core is the family's shared spine, the entry point is this domain's overlay. Copy both, or neither.
20
- - `ENFORCEMENT.md`: optional setup for CI and hooks.
21
-
22
- Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
23
-
24
- ## Honesty Contract
25
-
26
- 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.
27
-
28
- ## Marketing Values
29
-
30
- - **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.
31
- - **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.
32
- - **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.
33
- - **Internal consistency:** budget allocations sum, funnel math closes, every tactic serves an objective, every objective has a KPI. Checked mechanically, not rhetorically.
34
- - **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.
35
- - **Honesty about uncertainty:** assumptions are declared with ranges and confidence, never laundered into facts. A plan built on assumptions says so on page one.
36
- - **Measurability:** every tactic has a KPI, every objective a success signal, every plan explicit kill/scale criteria and a review cadence.
37
- - **Protect the Marketing Vision:** every downstream choice must serve a stated expected benefit or success signal; unauthorized scope is a vision divergence, not initiative.
38
-
39
- If a strategic choice looks obvious but you cannot trace it to evidence, research first.
40
-
41
- ## Rule Zero: Triage
42
-
43
-
44
- **Declare the level WITH the router verdict** (one line, for every engagement level above the trivial one): the result of the guide-router lookup, i.e. `Level: E2 · router: no match` or `Level: E3 · router: GUIDE_brand_voice.md → read`. The lookup is the consult trigger; making its result a declared output is what keeps it from being skipped — a level declared without a verdict makes "did not look" indistinguishable from "looked, nothing matched". Name the guide you matched, or `no match`.
45
-
46
- **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`agentic-sdlc`, `kb-agentic`), run the router in `routing.md`: it decides which lens's method and validation rules govern this unit of work. The trivial level never reaches it (L1 never reaches it), and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
47
-
48
- Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
49
-
50
- | Level | Criteria | Required process |
51
- |---|---|---|
52
- | **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. |
53
- | **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. Updating an existing strategy or campaign doc is a rewrite: full re-read, body to current state -- never an appended delta section. |
54
- | **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. |
55
- | **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. |
56
-
57
- Cross-cutting rules:
58
- - Every question to the user passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. The waves are where asking is planned; outside them the test gates each ask.
59
- - Anything touching pricing strategy, brand repositioning, or a new market entry is never E1: those decisions cascade.
60
- - If a bigger scope emerges during E1/E2 work (e.g. the campaign reveals there is no positioning), stop, reclassify and declare it.
61
- - When in doubt, pick the higher level.
62
- - 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.
63
-
64
- ## Write Triggers
65
-
66
- One event, one destination: when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it.
67
-
68
- | Document | Write trigger | Phase |
69
- |---|---|---|
70
- | `audit/handoff.md` (workstream registry) | **Never by hand — generated by `mkt_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 9 / session end |
71
- | `audit/HANDOFF_[engagement].md` | **One per OPEN engagement, with or without volatile state** — it is the authored home of that engagement's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. DELETED at closure — deleting it *is* removing the row. | 9 / session end |
72
- | `audit/project_notes.md` | A note true for the whole engagement portfolio rather than one engagement. Appended verbatim to the generated registry, so regenerating cannot destroy it. | 9 / session end |
73
- | `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. | 9 / session end |
74
- | `audit/HANDOFF_[engagement].md` | Session ends with that engagement unfinished AND there is volatile resume state. Ephemeral, deleted at closure. | 8 / 9 / session end |
75
- | `audit/reviews/REVIEW_LOG.md` | Every completed review — when and what to write is `review.md`; schema is `templates.md`. | 6 / 9 |
76
- | `reference/GUIDE_[topic].md` | Origin+purpose test (`guides.md`), or a proactive proposal the user accepted. | 8 / 9 |
77
- | `vision/` documents | Bootstrap as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation, and only after the blind check (`vision.md` §6). | 1 / 5 |
78
-
79
- ## Operating Modes
80
-
81
- ### Full Standalone
82
-
83
- Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
84
-
85
- Source of truth:
86
- - Vision: `mkt_docs/vision/MKT_VISION.md`, `principles.md`.
87
- - Evidence: `mkt_docs/research/evidence_ledger.md` + research documents in `mkt_docs/research/`.
88
- - Strategy artifacts: `mkt_docs/strategy/` (ICP_PERSONAS, THREAT_MAP, OBJECTIVES, STRATEGY).
89
- - Tactical artifacts: `mkt_docs/tactics/` (TACTICAL_PLAN, ACTION_90D, MEASUREMENT_PLAN).
90
- - Deliverables: `mkt_docs/deliverables/` (MARKETING_PLAN, ONE_PAGER, exports).
91
- - Spikes and handoff: `mkt_docs/spikes/`, `mkt_docs/audit/handoff.md`.
92
-
93
- Standalone mode is not reduced: it must handle full plans, campaigns, research spikes, reviews and closure without devPNT.
94
-
95
- ### Hybrid in symbiosis with devPNT
96
-
97
- Use this mode when the `devpnt_*` tools are available and point at the current project.
98
-
99
- Authoritative hierarchy:
100
- 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.
101
- 2. **devPNT Master Plan**: the marketing roadmap; milestones are plan cycles (a quarter, a launch, a market entry).
102
- 3. **devPNT Action Plan**: the nine phases of the active engagement as tactical nodes.
103
- 4. **devPNT governed artifacts**: the marketing artifact set (table below).
104
- 5. **Local `mkt_docs/`**: readable context, Standalone fallback, evidence ledger home, shadow/mirror when useful.
105
-
106
- ### Ownership matrix (the Hybrid seam)
107
-
108
- 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:
109
-
110
- | Artifact | Standalone master | Hybrid master (devPNT slot) | Mirror rule |
111
- |---|---|---|---|
112
- | Marketing vision | `vision/MKT_VISION.md` | M-VISION (`milestone_vision_<slug>`) | filesystem copy is a shadow; DB wins |
113
- | ICP & Personas | `strategy/ICP_PERSONAS.md` | `mkt_icp_personas` (D-UC slot) | shadow `SHADOW_[doc_key]_vX.Y.md` |
114
- | Threat map | `strategy/THREAT_MAP.md` | `mkt_threat_map` (P-TM slot) | shadow |
115
- | Objectives | `strategy/OBJECTIVES.md` | `mkt_objectives` | shadow |
116
- | Strategy | `strategy/STRATEGY.md` | `mkt_strategy` (E-ISP slot) | shadow, exported BEFORE tactics work |
117
- | Tactical plan | `tactics/TACTICAL_PLAN.md` | `mkt_tactical_plan` (E-TDD slot) | shadow, exported BEFORE action phase |
118
- | Measurement plan | `tactics/MEASUREMENT_PLAN.md` | `mkt_measurement_plan` (E-TP slot) | shadow |
119
- | 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 |
120
- | Final plan + one-pager | `deliverables/` | assembled from ACCEPTED artifact versions | PDF via `devpnt_generate_document_pdf` when available |
121
- | Handoff | `audit/handoff.md` | `audit/handoff.md` | always filesystem |
122
-
123
- Hybrid rules:
124
- - devPNT is the governed source for plans and strategy artifacts; do not create a second truth in `mkt_docs/`.
125
- - The skill stays autonomous: if devPNT is not there, switch to Standalone without losing capability.
126
- - If the user request, the local vision and the M-VISION diverge, stop and make the conflict explicit.
127
- - Never auto-accept devPNT proposals: present the preview and wait for explicit confirmation.
128
- - 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.
129
-
130
- ## The Three Engineered Guarantees
131
-
132
- Every E3 (and every E2 with numbers) is bound by these. They are the product; the phases below exist to feed them.
133
-
134
- 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.
135
- 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.
136
- 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.
137
-
138
- ## E3 Workflow (nine phases on the SOSTAC spine)
139
-
140
- 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.
141
-
142
- ### 1. Intake & Triage
143
- - Read the docs root's `README.md`, `INDEX.md` and `reference/INDEX.md` (the guide router; the docs root is `mkt_docs/` by default, `ai_docs/` on a migrated tree) before touching the plan. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide — a brand guideline, a tone-of-voice SOP, an agency playbook — already governs the work you are about to do.
144
- - Read `audit/handoff.md` under the docs root, the workstream registry: one row per open engagement. Volatile resume state for an unfinished one lives in `audit/HANDOFF_[engagement].md`, which is ephemeral and deleted at closure.
145
- - 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.
146
- - Hybrid: bootstrap devPNT, restore Master/Action Plan and any existing marketing artifacts before asking the user anything they already answered.
147
-
148
- ### 2. Discovery (Situation — internal)
149
- - Run elicitation **Wave 1** (`elicitation.md`): business facts only, plain language, max 4 questions per round, options where a real choice exists.
150
- - Every fact captured becomes a `FACT` ledger entry. Draft `MKT_VISION.md` (Status: DRAFT) from the answers.
151
- - **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.
152
-
153
- ### 3. Research (Situation — external)
154
- - Follow `research.md`. Prefer the deep-research skill as the engine when available; fallback to the manual playbook.
155
- - Mandatory sweeps: market sizing (bottom-up preferred), competitor scan, voice-of-customer mining, channel benchmarks. Every number lands in the ledger with source + date.
156
- - Two independent sources for any number that will drive a budget decision.
157
-
158
- ### 4. Situation Analysis
159
- - Synthesize research into `ICP_PERSONAS.md` (every persona trait traces to VoC evidence) and `THREAT_MAP.md` (competitor moves, risks, mitigations).
160
- - SWOT built from ledger entries, not adjectives. PESTEL / Five Forces only when the market warrants them (`frameworks.md` says when).
161
-
162
- ### 5. Objectives — **USER GATE**
163
- - Run elicitation **Wave 2** (ambition, trade-offs, risk appetite, timeline).
164
- - Draft `OBJECTIVES.md`: SMART objectives (`O1`, `O2`, ...) + KPI tree. Each objective cites the ledger entries that make it plausible.
165
- - The user approves objectives before strategy. Objectives the user did not set are proposals, and say so.
166
-
167
- ### 6. Strategy — **REVIEW + USER GATE**
168
- - **Design review gate:** the strategy is reviewed by somebody other than its author before any tactic is executed — a subagent with fresh context, or a declared self-pass when no higher rung is usable — a permission-gated rung is asked about, never silently skipped (`review.md`). Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md` under the docs root. A strategy reviewed only by the person who wrote it is not reviewed.
169
- - Draft `STRATEGY.md`: segmentation, targeting choice with rationale, positioning (Dunford components + statement), messaging house.
170
- - **Adversarial review** (`review.md`) before the user sees it. Fix or answer every finding.
171
- - The user approves the strategy. Hybrid: propose as governed doc, user accepts in devPNT.
172
-
173
- ### 7. Tactics — **VALIDATOR GATE**
174
- - Run elicitation **Wave 3** (execution capacity: who writes, who runs ads, tooling, sales follow-up).
175
- - Draft `TACTICAL_PLAN.md`: channel table (channel | objective served | KPI | budget | owner), budget allocation, funnel model per acquisition channel.
176
- - `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.
177
-
178
- ### 8. Action
179
- - **Isolate the work (Branch/worktree hygiene).** Execution rewrites plan documents other people are reading: do it on a branch or a worktree, never directly on the shared plan.
180
- - **Consult (before acting)**: **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read.
181
- - **Opt-in subagent execution**: for an approved plan, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
182
- - Draft `ACTION_90D.md`: sequenced 90-day plan (what starts when, owner, dependency), first 2 weeks day-level, rest weekly.
183
-
184
- ### 9. Control & Packaging — **FINAL REVIEW GATE**
185
- - **Propose proactively**: if the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
186
- - Draft `MEASUREMENT_PLAN.md`: KPI tree with targets and benchmark references, review cadence, explicit kill/scale criteria per channel.
187
- - Assemble `MARKETING_PLAN.md` (the SOSTAC deliverable) and `ONE_PAGER.md` from the approved artifacts — assembly, not rewriting; on divergence the approved artifact wins.
188
- - Final adversarial review on the assembled plan + `mkt_check.py check` CLEAN.
189
- - Offer exports: PDF, slide deck, budget spreadsheet (use the client's document skills when available).
190
- - Update `handoff.md`. Hybrid: mark plan nodes DONE only after the user accepts the final artifacts.
191
-
192
- ## E2 Workflow (campaign)
193
-
194
- 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.
195
-
196
- ## mkt_docs documents: indexes + lifecycle
197
-
198
- - **`mkt_docs/README.md` (curated, by hand):** reading priority, few lines.
199
- - **`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.
200
- - `research/`, `spikes/`, `audit/` are discovery-by-grep: they do not enter the manifest. Research freshness is carried by ledger dates, not by the manifest.
201
-
202
- Every canonical document opens with frontmatter:
203
-
204
- ```markdown
205
- ---
206
- description: One line — what it is and when to read it.
207
- status: CURRENT # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
208
- supersedes: old_doc.md # only if it replaces another doc
209
- ---
210
- ```
211
-
212
- `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`.
213
-
214
- ## Deliverable quality bar
215
-
216
- The final plan must be recognizable by a marketing professional:
217
- - SOSTAC section structure, executive summary first.
218
- - Every number carries `[EV-nn]`; the ledger ships as an appendix.
219
- - Assumptions section on page one when material assumptions exist.
220
- - Positioning passes the swap test; messaging house has proof points, not slogans.
221
- - Budget table, funnel model, 90-day plan and kill/scale criteria present — a plan without a control loop is a brochure.
222
-
223
- ## Reading the shared doctrine from this lens
224
-
225
- `review.md`, `dispatch.md` and `guides.md` are the family's shared spine,
226
- byte-identical in every distribution, written in the family's neutral
227
- vocabulary. Reading them from this lens: where they say `sdlc_check.py`,
228
- read `mkt_check.py`; where they say "Phase 3 / Phase 5 closure", read this
229
- workflow's phase 6 (strategy review) and phase 9 (control & packaging);
230
- where they say ANALYSIS/feature, read this lens's governed artifacts and
231
- engagement. The procedures bind as written; only the names translate.
232
-
233
- ## Mechanical Enforcement
234
-
235
- The prompt is not enforcement. When the project needs repeatable guarantees:
236
- - read `ENFORCEMENT.md`;
237
- - use `scripts/mkt_check.py validate --strict` in CI;
238
- - run `scripts/mkt_check.py check` before declaring any E2/E3 deliverable done.
239
-
240
- The validator is a support, not a universal prerequisite: the skill must stay usable in environments without Python, declaring what it cannot verify automatically.
1
+ ---
2
+ name: mkt-agentic-sdlc
3
+ version: 0.8.0
4
+ 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.
5
+ author: Antonio Pinto (https://github.com/Antoneeo)
6
+ copyright: (c) 2026 Antonio Pinto
7
+ ---
8
+
9
+ # Marketing Agentic SDLC
10
+
11
+ 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.
12
+
13
+ Support files in the skill directory:
14
+ - `frameworks.md`: which professional framework to use in which phase (SOSTAC, STP, JTBD, positioning, KPI tree) — and when NOT to use one.
15
+ - `elicitation.md`: the question waves and the only-facts-you-own rule.
16
+ - `research.md`: the research playbook and the evidence ledger discipline.
17
+ - `templates.md`: templates for every artifact and deliverable.
18
+ - `review.md`: the family's shared review discipline (independence ladder, rounds, log). The marketing-specific attack surface — swap test, untraced numbers, orphan tactics, missing kill/scale — lives in `frameworks.md`'s falsification rules; the adversarial CMO review applies them through `review.md`'s procedure.
19
+ - `scripts/mkt_check.py` + `scripts/sdlc_core.py`: the mechanical validator (`check`, `validate`, `ledger`, `budget`, `funnel`, `trace`, `index`, plus the spine's `stale`/`mark`/`gate`/`orient`/`plan`/`migrate`). Two files: the core is the family's shared spine, the entry point is this domain's overlay. Copy both, or neither.
20
+ - `ENFORCEMENT.md`: optional setup for CI and hooks.
21
+
22
+ Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
23
+
24
+ ## Honesty Contract
25
+
26
+ 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.
27
+
28
+ ## Marketing Values
29
+
30
+ - **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.
31
+ - **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.
32
+ - **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.
33
+ - **Internal consistency:** budget allocations sum, funnel math closes, every tactic serves an objective, every objective has a KPI. Checked mechanically, not rhetorically.
34
+ - **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.
35
+ - **Honesty about uncertainty:** assumptions are declared with ranges and confidence, never laundered into facts. A plan built on assumptions says so on page one.
36
+ - **Measurability:** every tactic has a KPI, every objective a success signal, every plan explicit kill/scale criteria and a review cadence.
37
+ - **Protect the Marketing Vision:** every downstream choice must serve a stated expected benefit or success signal; unauthorized scope is a vision divergence, not initiative.
38
+
39
+ If a strategic choice looks obvious but you cannot trace it to evidence, research first.
40
+
41
+ ## Rule Zero: Triage
42
+
43
+
44
+ **Declare the level WITH the router verdict** (one line, for every engagement level above the trivial one): the result of the guide-router lookup, i.e. `Level: E2 · router: no match` or `Level: E3 · router: GUIDE_brand_voice.md → read`. The lookup is the consult trigger; making its result a declared output is what keeps it from being skipped — a level declared without a verdict makes "did not look" indistinguishable from "looked, nothing matched". Name the guide you matched, or `no match`.
45
+
46
+ **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`agentic-sdlc`, `kb-agentic`), run the router in `routing.md`: it decides which lens's method and validation rules govern this unit of work. The trivial level never reaches it (L1 never reaches it), and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
47
+
48
+ Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
49
+
50
+ | Level | Criteria | Required process |
51
+ |---|---|---|
52
+ | **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. |
53
+ | **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. Updating an existing strategy or campaign doc is a rewrite: full re-read, body to current state -- never an appended delta section. |
54
+ | **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. |
55
+ | **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. |
56
+
57
+ Cross-cutting rules:
58
+ - Every question to the user passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. The waves are where asking is planned; outside them the test gates each ask.
59
+ - Anything touching pricing strategy, brand repositioning, or a new market entry is never E1: those decisions cascade.
60
+ - If a bigger scope emerges during E1/E2 work (e.g. the campaign reveals there is no positioning), stop, reclassify and declare it.
61
+ - When in doubt, pick the higher level.
62
+ - 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.
63
+
64
+ ## Write Triggers
65
+
66
+ One event, one destination: when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it.
67
+
68
+ | Document | Write trigger | Phase |
69
+ |---|---|---|
70
+ | `audit/handoff.md` (workstream registry) | **Never by hand — generated by `mkt_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 9 / session end |
71
+ | `audit/HANDOFF_[engagement].md` | **One per OPEN engagement, with or without volatile state** — it is the authored home of that engagement's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. DELETED at closure — deleting it *is* removing the row. | 9 / session end |
72
+ | `audit/project_notes.md` | A note true for the whole engagement portfolio rather than one engagement. Appended verbatim to the generated registry, so regenerating cannot destroy it. | 9 / session end |
73
+ | `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. | 9 / session end |
74
+ | `audit/HANDOFF_[engagement].md` | Session ends with that engagement unfinished AND there is volatile resume state. Ephemeral, deleted at closure. | 8 / 9 / session end |
75
+ | `audit/reviews/REVIEW_LOG.md` | Every completed review — when and what to write is `review.md`; schema is `templates.md`. | 6 / 9 |
76
+ | `reference/GUIDE_[topic].md` | Origin+purpose test (`guides.md`), or a proactive proposal the user accepted. | 8 / 9 |
77
+ | `vision/` documents | Bootstrap as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation, and only after the blind check (`vision.md` §6). | 1 / 5 |
78
+
79
+ ## Operating Modes
80
+
81
+ ### Full Standalone
82
+
83
+ Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
84
+
85
+ Source of truth:
86
+ - Vision: `mkt_docs/vision/MKT_VISION.md`, `principles.md`.
87
+ - Evidence: `mkt_docs/research/evidence_ledger.md` + research documents in `mkt_docs/research/`.
88
+ - Strategy artifacts: `mkt_docs/strategy/` (ICP_PERSONAS, THREAT_MAP, OBJECTIVES, STRATEGY).
89
+ - Tactical artifacts: `mkt_docs/tactics/` (TACTICAL_PLAN, ACTION_90D, MEASUREMENT_PLAN).
90
+ - Deliverables: `mkt_docs/deliverables/` (MARKETING_PLAN, ONE_PAGER, exports).
91
+ - Spikes and handoff: `mkt_docs/spikes/`, `mkt_docs/audit/handoff.md`.
92
+
93
+ Standalone mode is not reduced: it must handle full plans, campaigns, research spikes, reviews and closure without devPNT.
94
+
95
+ ### Hybrid in symbiosis with devPNT
96
+
97
+ Use this mode when the `devpnt_*` tools are available and point at the current project.
98
+
99
+ Authoritative hierarchy:
100
+ 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.
101
+ 2. **devPNT Master Plan**: the marketing roadmap; milestones are plan cycles (a quarter, a launch, a market entry).
102
+ 3. **devPNT Action Plan**: the nine phases of the active engagement as tactical nodes.
103
+ 4. **devPNT governed artifacts**: the marketing artifact set (table below).
104
+ 5. **Local `mkt_docs/`**: readable context, Standalone fallback, evidence ledger home, shadow/mirror when useful.
105
+
106
+ ### Ownership matrix (the Hybrid seam)
107
+
108
+ 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:
109
+
110
+ | Artifact | Standalone master | Hybrid master (devPNT slot) | Mirror rule |
111
+ |---|---|---|---|
112
+ | Marketing vision | `vision/MKT_VISION.md` | M-VISION (`milestone_vision_<slug>`) | filesystem copy is a shadow; DB wins |
113
+ | ICP & Personas | `strategy/ICP_PERSONAS.md` | `mkt_icp_personas` (D-UC slot) | shadow `SHADOW_[doc_key]_vX.Y.md` |
114
+ | Threat map | `strategy/THREAT_MAP.md` | `mkt_threat_map` (P-TM slot) | shadow |
115
+ | Objectives | `strategy/OBJECTIVES.md` | `mkt_objectives` | shadow |
116
+ | Strategy | `strategy/STRATEGY.md` | `mkt_strategy` (E-ISP slot) | shadow, exported BEFORE tactics work |
117
+ | Tactical plan | `tactics/TACTICAL_PLAN.md` | `mkt_tactical_plan` (E-TDD slot) | shadow, exported BEFORE action phase |
118
+ | Measurement plan | `tactics/MEASUREMENT_PLAN.md` | `mkt_measurement_plan` (E-TP slot) | shadow |
119
+ | 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 |
120
+ | Final plan + one-pager | `deliverables/` | assembled from ACCEPTED artifact versions | PDF via `devpnt_generate_document_pdf` when available |
121
+ | Handoff | `audit/handoff.md` | `audit/handoff.md` | always filesystem |
122
+
123
+ Hybrid rules:
124
+ - devPNT is the governed source for plans and strategy artifacts; do not create a second truth in `mkt_docs/`.
125
+ - The skill stays autonomous: if devPNT is not there, switch to Standalone without losing capability.
126
+ - If the user request, the local vision and the M-VISION diverge, stop and make the conflict explicit.
127
+ - Never auto-accept devPNT proposals: present the preview and wait for explicit confirmation.
128
+ - 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.
129
+
130
+ ## The Three Engineered Guarantees
131
+
132
+ Every E3 (and every E2 with numbers) is bound by these. They are the product; the phases below exist to feed them.
133
+
134
+ 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.
135
+ 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.
136
+ 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.
137
+
138
+ ## E3 Workflow (nine phases on the SOSTAC spine)
139
+
140
+ 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.
141
+
142
+ ### 1. Intake & Triage
143
+ - Read the docs root's `README.md`, `INDEX.md` and `reference/INDEX.md` (the guide router; the docs root is `mkt_docs/` by default, `ai_docs/` on a migrated tree) before touching the plan. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide — a brand guideline, a tone-of-voice SOP, an agency playbook — already governs the work you are about to do.
144
+ - Read `audit/handoff.md` under the docs root, the workstream registry: one row per open engagement. Volatile resume state for an unfinished one lives in `audit/HANDOFF_[engagement].md`, which is ephemeral and deleted at closure.
145
+ - 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.
146
+ - Hybrid: bootstrap devPNT, restore Master/Action Plan and any existing marketing artifacts before asking the user anything they already answered.
147
+
148
+ ### 2. Discovery (Situation — internal)
149
+ - Run elicitation **Wave 1** (`elicitation.md`): business facts only, plain language, max 4 questions per round, options where a real choice exists.
150
+ - Every fact captured becomes a `FACT` ledger entry. Draft `MKT_VISION.md` (Status: DRAFT) from the answers.
151
+ - **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.
152
+
153
+ ### 3. Research (Situation — external)
154
+ - Follow `research.md`. Prefer the deep-research skill as the engine when available; fallback to the manual playbook.
155
+ - Mandatory sweeps: market sizing (bottom-up preferred), competitor scan, voice-of-customer mining, channel benchmarks. Every number lands in the ledger with source + date.
156
+ - Two independent sources for any number that will drive a budget decision.
157
+
158
+ ### 4. Situation Analysis
159
+ - Synthesize research into `ICP_PERSONAS.md` (every persona trait traces to VoC evidence) and `THREAT_MAP.md` (competitor moves, risks, mitigations).
160
+ - SWOT built from ledger entries, not adjectives. PESTEL / Five Forces only when the market warrants them (`frameworks.md` says when).
161
+
162
+ ### 5. Objectives — **USER GATE**
163
+ - Run elicitation **Wave 2** (ambition, trade-offs, risk appetite, timeline).
164
+ - Draft `OBJECTIVES.md`: SMART objectives (`O1`, `O2`, ...) + KPI tree. Each objective cites the ledger entries that make it plausible.
165
+ - The user approves objectives before strategy. Objectives the user did not set are proposals, and say so.
166
+
167
+ ### 6. Strategy — **REVIEW + USER GATE**
168
+ - **Design review gate:** the strategy is reviewed by somebody other than its author before any tactic is executed — a subagent with fresh context, or a declared self-pass when no higher rung is usable — a permission-gated rung is asked about, never silently skipped (`review.md`). Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md` under the docs root. A strategy reviewed only by the person who wrote it is not reviewed.
169
+ - Draft `STRATEGY.md`: segmentation, targeting choice with rationale, positioning (Dunford components + statement), messaging house.
170
+ - **Adversarial review** (`review.md`) before the user sees it. Fix or answer every finding.
171
+ - The user approves the strategy. Hybrid: propose as governed doc, user accepts in devPNT.
172
+
173
+ ### 7. Tactics — **VALIDATOR GATE**
174
+ - Run elicitation **Wave 3** (execution capacity: who writes, who runs ads, tooling, sales follow-up).
175
+ - Draft `TACTICAL_PLAN.md`: channel table (channel | objective served | KPI | budget | owner), budget allocation, funnel model per acquisition channel.
176
+ - `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.
177
+
178
+ ### 8. Action
179
+ - **Isolate the work (Branch/worktree hygiene).** Execution rewrites plan documents other people are reading: do it on a branch or a worktree, never directly on the shared plan.
180
+ - **Consult (before acting)**: **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read.
181
+ - **Opt-in subagent execution**: for an approved plan, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
182
+ - Draft `ACTION_90D.md`: sequenced 90-day plan (what starts when, owner, dependency), first 2 weeks day-level, rest weekly.
183
+
184
+ ### 9. Control & Packaging — **FINAL REVIEW GATE**
185
+ - **Propose proactively**: if the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
186
+ - Draft `MEASUREMENT_PLAN.md`: KPI tree with targets and benchmark references, review cadence, explicit kill/scale criteria per channel.
187
+ - Assemble `MARKETING_PLAN.md` (the SOSTAC deliverable) and `ONE_PAGER.md` from the approved artifacts — assembly, not rewriting; on divergence the approved artifact wins.
188
+ - Final adversarial review on the assembled plan + `mkt_check.py check` CLEAN.
189
+ - Offer exports: PDF, slide deck, budget spreadsheet (use the client's document skills when available).
190
+ - Update `handoff.md`. Hybrid: mark plan nodes DONE only after the user accepts the final artifacts.
191
+
192
+ ## E2 Workflow (campaign)
193
+
194
+ 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.
195
+
196
+ ## mkt_docs documents: indexes + lifecycle
197
+
198
+ - **`mkt_docs/README.md` (curated, by hand):** reading priority, few lines.
199
+ - **`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.
200
+ - `research/`, `spikes/`, `audit/` are discovery-by-grep: they do not enter the manifest. Research freshness is carried by ledger dates, not by the manifest.
201
+
202
+ Every canonical document opens with frontmatter:
203
+
204
+ ```markdown
205
+ ---
206
+ description: One line — what it is and when to read it.
207
+ status: CURRENT # CURRENT | SUPERSEDED | DRAFT | DEPRECATED
208
+ supersedes: old_doc.md # only if it replaces another doc
209
+ ---
210
+ ```
211
+
212
+ `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`.
213
+
214
+ ## Deliverable quality bar
215
+
216
+ The final plan must be recognizable by a marketing professional:
217
+ - SOSTAC section structure, executive summary first.
218
+ - Every number carries `[EV-nn]`; the ledger ships as an appendix.
219
+ - Assumptions section on page one when material assumptions exist.
220
+ - Positioning passes the swap test; messaging house has proof points, not slogans.
221
+ - Budget table, funnel model, 90-day plan and kill/scale criteria present — a plan without a control loop is a brochure.
222
+
223
+ ## Reading the shared doctrine from this lens
224
+
225
+ `review.md`, `dispatch.md` and `guides.md` are the family's shared spine,
226
+ byte-identical in every distribution, written in the family's neutral
227
+ vocabulary. Reading them from this lens: where they say `sdlc_check.py`,
228
+ read `mkt_check.py`; where they say "Phase 3 / Phase 5 closure", read this
229
+ workflow's phase 6 (strategy review) and phase 9 (control & packaging);
230
+ where they say ANALYSIS/feature, read this lens's governed artifacts and
231
+ engagement. The procedures bind as written; only the names translate.
232
+
233
+ ## Mechanical Enforcement
234
+
235
+ The prompt is not enforcement. When the project needs repeatable guarantees:
236
+ - read `ENFORCEMENT.md`;
237
+ - use `scripts/mkt_check.py validate --strict` in CI;
238
+ - run `scripts/mkt_check.py check` before declaring any E2/E3 deliverable done.
239
+
240
+ 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/review.md CHANGED
@@ -94,6 +94,23 @@ Hybrid project's devPNT gates write to the same file.
94
94
  The log is how the gate's value is measured over time; skipping it makes the gate
95
95
  unfalsifiable, the same defect as an unnamed EXISTS or a faked router verdict.
96
96
 
97
+ **Revise means converge, not accrete.** Two revision failure modes generate their
98
+ own findings and can make the cap unreachable honestly. (1) *Patch-on-patch*:
99
+ each round's fixes are grafted onto the previous text until stale counts,
100
+ duplicated sections and internal contradictions are findings the revisions
101
+ themselves created. When a round's findings are of that artifact-consistency
102
+ class — and at the latest before a round-3 attempt — rewrite the artifact lean
103
+ and operative against the checklist instead of patching again; a from-scratch
104
+ rewrite is cheaper than a burned round. (2) *Revision narrative in the
105
+ artifact*: the artifact under review carries its own review archaeology
106
+ ("v1.2 fixed…", "as the round-2 review noted…"). An artifact states what IS,
107
+ once; how it got there lives in the REVIEW_LOG row's notes, never in the
108
+ artifact — archaeology bloats the object under review and every stale
109
+ self-reference is a future finding. Field measurement (2026-08): an artifact
110
+ that had grown to ~1,250 lines across eight failing rounds passed on the round
111
+ after a ~500-line operative rewrite moved the history out — the rewrite removed
112
+ an entire finding class.
113
+
97
114
  **The reviewer is read-only and advisory.** It never edits, never commits, never
98
115
  marks anything DONE, and a PASS is not an approval to merge — the human owns that.
99
116
 
@@ -124,6 +141,26 @@ When you hand work to a reviewer (human or agent), give them:
124
141
  should have been. The design reviewer checks that every threat surface the change
125
142
  touches has a matching security requirement.
126
143
 
144
+ - **The severity contract**: state with the request what counts as a blocker
145
+ versus a lesser finding. A blocker is *unfit-to-proceed* evidence only — a
146
+ false claim about existing code, a published falsehood, a missing impacted
147
+ file, an unresolvable internal contradiction, a real regression; an
148
+ improvement idea, a wish, or a style preference is at most a WARN and never
149
+ fails the artifact. An uncalibrated "hunt hard" mandate produces
150
+ blocker-inflated rounds that fail artifacts on wishes — each one burns a
151
+ round from the cap of 3 and patches the artifact for prose, the accretion
152
+ failure the round-cap rule names. Stating the taxonomy calibrates the
153
+ *scale*; it never pre-judges any specific finding (that stays forbidden
154
+ below) — the reviewer still decides where every finding lands.
155
+
156
+ **Pre-audit before you request.** Before handing the artifact over, run a
157
+ scripted author pre-audit: mechanically resolve every `file:line` / symbol
158
+ anchor the artifact cites against the real tree, and recount every count it
159
+ states — with a script, not by eye. Anchors rot between drafts, and a reviewer
160
+ that trips on a broken anchor spends its round proving your citation instead of
161
+ your design. Measured cost is near zero (one grep-loop); measured catch: four
162
+ rotted anchors in a single artifact, pre-review.
163
+
127
164
  **The verdict travels back as the reviewer's own final output** — the text it
128
165
  returns when it finishes, nothing else. A reviewer that tries to message the
129
166
  requester mid-run depends on a delivery channel it cannot verify (a subagent
@@ -301,6 +338,20 @@ When you are the reviewer:
301
338
  NOT checked here — architecture-awareness is the Capability Ledger / Impact
302
339
  review's job; a clause for it would duplicate that.) A lens whose template
303
340
  defines no such section (knowledge, marketing) never fires this clause.
341
+ - **Behavioural-claim probes (same reviews; fires only in the lens whose
342
+ SKILL.md defines Execute-Before-Specify — the code lens today; that paragraph
343
+ is the owning definition — cite it, never restate it).** On an L3 design
344
+ artifact, a claim of the form "the code today does X" must trace to an
345
+ assertion in the artifact's shipped harness
346
+ (`ai_docs/solutions/harness_[feature]/`): the check is mechanical — re-run
347
+ the harness and compare, instead of re-deriving the claims by reading. Three
348
+ findings live here and nowhere else: a behavioural claim backed by no probe
349
+ (report it as unproven — reading the source yourself is the same
350
+ insufficient evidence the rule bans for the author); a harness absent while
351
+ the prose carries behavioural claims; and a probe that no longer passes
352
+ against the current tree. Structural facts (a file exists, a symbol's
353
+ signature, its callers) are the blast-radius clause's territory, never probe
354
+ findings. A lens whose SKILL.md defines no such duty never fires this clause.
304
355
 
305
356
  ## Anti-patterns
306
357