arkaos 4.26.0 → 4.27.0

package/departments/marketing/skills/paid-campaign/references/meta-decision-system.md

@@ -0,0 +1,143 @@
+# Meta Decision System (B2B)
+
+A quantified kill/keep/scale engine for Meta ads. Every threshold derives from one anchor number, so decisions become arithmetic instead of vibes. Pairs with the strategy-level Meta playbook in SKILL.md (creative-as-targeting, creative volume) — this file is the *operating* layer.
+
+## Contents
+
+- TCPL: the anchor variable
+- The ad-count ceiling
+- Two-campaign structure (Scaling / Testing)
+- Stage 1: delivery check (day 7)
+- Stage 2: quality evaluation (weekly)
+- Graduation criteria
+- Fatigue detection
+- Swap rules
+- Creative production math
+- Scaling protocol
+- Weekly cadence
+- Lead forms and social amnesia
+- Advantage+ transition
+- Benchmarks and seasonality
+
+## TCPL: the anchor variable
+
+TCPL = **Target Cost Per Qualified Lead** (qualified = meets your ICP bar, not just a form-fill). Set it one of three ways:
+
+1. **From deal math (best):** TCPL = target cost per demo × qualified-lead-to-demo rate. ($2,000/demo × 0.28 = $560.)
+2. **From history:** TCPL = trailing 30-day CPL(qualified) × 0.80 — a 20% improvement is achievable through operational cleanup alone (killing zero-QL ads, graduating winners). Once you have both, use whichever is tighter.
+3. **New account:** target CAC × qualified-lead-to-customer rate, or a placeholder from your ACV tier; replace with method 2 after 30 days.
+
+Every rule below is expressed in multiples of TCPL. Review TCPL monthly.
+
+## The ad-count ceiling
+
+More active ads than your budget can feed = every ad starves and nothing gets a fair read.
+
+**Ceiling = (daily budget × 14) / (2 × TCPL)** — i.e., over a 14-day evaluation window, each ad needs at least 2× TCPL of spend to be judged.
+
+$1,000/day at $500 TCPL → ceiling of 14 ads; run **6–10** (winners + 2–3 test slots). At the ceiling, launching a new test requires killing something first.
+
+## Two-campaign structure (Scaling / Testing)
+
+Run two CBO campaigns over the **same audience**:
+
+- **Scaling campaign (~80% of budget)** — holds only graduated, proven ads.
+- **Testing campaign (~20%)** — holds new concepts and iterations, with its own protected budget.
+
+Why: inside a single CBO, proven ads always starve new ads — tests never get enough spend to be judged. Why not ABO for testing: equal forced distribution keeps spending on ads Meta has already deprioritized. The separation is *budget protection*, not audience segmentation.
+
+**Image-first validation:** launch new concepts as statics first; only produce the video/carousel/UGC version after the image passes the checks below. Exception: concepts that are inherently video (testimonial, demo, UGC).
+
+## Stage 1: delivery check (day 7)
+
+CBO's spend allocation is itself a signal — Meta pre-screens your ads. At day 7 for each test ad:
+
+- **Fair share test:** minimum expected spend = (campaign daily budget ÷ active ads) × 7 × 0.5. Below that → **kill** (Meta actively deprioritized it). Zero spend → kill immediately.
+- **Ongoing:** if an ad has spent ≥ 1× TCPL lifetime AND averaged under ~$10/day over the last 7 days → kill. (The lifetime-spend gate stops you from killing ads CBO simply hasn't explored yet.)
+
+When iterating on a delivery-killed ad, change the **hook/visual/format only** — the audience never got far enough for copy or CTA to matter.
+
+## Stage 2: quality evaluation (weekly, rolling 14-day data)
+
+Run in order; stop at the first triggered action:
+
+1. **Data gate:** spend < 3× TCPL → **wait** (not enough signal). At true cost-per-QL = target, 3× TCPL of spend should produce ~3 qualified leads; zero QLs at that spend is ~5% probability — so judging at 3× gives ~95% confidence without wasting budget (2× has a 13% false-negative rate; 5× overpays for certainty).
+2. **Zero pixel leads** at ≥3× TCPL → **swap and abandon the concept** (don't iterate a dead concept).
+3. **Quality check** (the layer Meta can't see — requires your CRM):
+   - Pixel leads but zero qualified → swap; keep the format, change the angle.
+   - Qualified rate <40% → swap; the ad attracts the wrong people. Add ICP-filtering language. (At 40% QL rate, true cost per QL is 2.5× the pixel CPL you see in Ads Manager — two ads identical in-platform can differ 60%+ in real cost.)
+   - 40–60% → monitor one more week. ≥60% → proceed.
+4. **Cost check:** cost per QL ≤ TCPL → candidate winner. 1–1.5× TCPL → monitor (normal variance). >1.5× TCPL → swap (structural underperformance, not noise).
+
+## Graduation criteria (Testing → Scaling)
+
+Graduate only when **all** are true: ≥5 qualified leads · qualified rate ≥60% · cost per QL ≤ TCPL · running ≥14 days · ≥1 QL in the last 7 days.
+
+## Fatigue detection
+
+Frequency bands by campaign type (safe / warning / critical):
+
+| Campaign type | Safe | Warning | Critical |
+|---|---|---|---|
+| Cold prospecting | 1.0–2.5 | 2.5–4.0 | >4.0 |
+| Retargeting | 2.0–4.0 | 4.0–6.0 | >6.0 |
+| ABM (small audiences) | 2.0–5.0 | 5.0–8.0 | >8.0 |
+
+Other signals, in urgency order: CTR down 20%+ from baseline over 7 days; CPM up 30%+ over 2 weeks (leading indicator — moves before CTR); ad relevance rankings "below average"; CPA up with stable targeting.
+
+For **scaling-campaign ads**, apply a deliberately stricter bar than the general bands — these ads carry ~80% of spend, so fatigue there costs the most: warning at frequency 3.0–3.5 or cost +20% → start 2 iterations now (they take ~14 days to be ready); swap at >3.5, cost +40%, or >1.5× TCPL for 2 weeks.
+
+**Lifespan expectations (B2B):** statics 14–28 days; short video and carousels 21–35; UGC/testimonial 28–42. Small B2B audiences build frequency fast — plan refresh every 14–21 days.
+
+**Retire (don't iterate)** when CTR drops 30%+ from peak or frequency crosses the campaign type's critical band above — the concept is exhausted, not the execution.
+
+**Rotation without resetting learning:** never edit creative inside a performing ad — that resets the learning phase. Launch new ads alongside existing ones, or spin up a new ad set with the same targeting. Pausing doesn't reset; editing does.
+
+## Swap rules
+
+**Never pause without a replacement.** Keep 2–3 iterations staged; replacement live within 7 days, immediately for critical fatigue. If the pipeline is empty, redirect the budget to proven ads rather than leaving a zombie running. What to change depends on why it died: delivery kill → hook/visual; quality kill → angle and ICP language; cost kill → offer and audience; fatigue → fresh execution of the same proven concept.
+
+## Creative production math
+
+- **Test throughput** ≈ (monthly budget × 0.20) ÷ (3 × TCPL), per month. Delivery kills free budget early, so actual throughput runs ~1.5–2× the base rate.
+- **Win rates:** iterations on winners ~25%; brand-new concepts ~10%; blended ~1 in 6. To get N winners, plan ~6× N tests.
+- **Minimum proven-ad inventory** ≈ monthly budget ÷ $5,000 — each proven B2B ad absorbs roughly $5K/month before fatiguing. **You cannot scale budget ahead of creative supply**; if proven ads < minimum, fix the creative deficit before raising budget.
+- **Iteration priority** when refreshing a winner (ranked by impact): 1. hook (changes who stops) → 2. visual treatment → 3. format → 4. body copy/CTA.
+
+## Scaling protocol
+
+Scale only when all: proven-ad count meets the next budget level's minimum; account frequency <3.0; cost per QL ≤ TCPL for 2+ consecutive weeks; 3+ replacements staged.
+
+- **Rate:** +20% every 5 days. Never +30% or more in one move — that resets learning.
+- **Rollback trigger:** cost per QL >1.5× TCPL after a scale step → cut budget 20–30% immediately, stabilize 2 weeks, resume at +10% per week.
+- **Hitting the wall** (account-wide average frequency >3.5 — an account-level *scale* guardrail, distinct from the per-ad fatigue bands above): expand lookalikes 1% → 2–3%, add new seed audiences, test broad, activate cross-channel UTM audiences (see [ABM playbook](abm-playbook.md)), re-open remarketing.
+
+## Weekly cadence
+
+- **Monday — decision day:** pull rolling 14-day data; run Stage 2 on every test ad; run the fatigue check on every scaling ad.
+- **Wednesday — launch day:** launch new tests into freed slots; run Stage 1 on ads that hit day 7.
+- **Friday — scaling day:** apply scale steps or rollbacks.
+- **Monthly:** creative library audit + TCPL review.
+
+## Lead forms and social amnesia
+
+The #1 B2B Meta lead-quality problem: frictionless auto-filled forms produce leads who don't remember converting ("social amnesia"). **Intentional friction = awareness = quality:**
+
+- Use **Higher Intent** form type (adds a review step), not More Volume.
+- **Require work email** — it can't auto-fill from the Facebook profile, forcing a conscious act. This is the single biggest quality lever.
+- Add 1–3 multiple-choice qualification questions (4+ spikes abandonment), ordered easiest → hardest.
+- Confirmation message sets expectations for what happens next (combats amnesia at the follow-up stage).
+
+Lead form vs. landing page: LP converting ≥5% → use the LP; LP under ~2% → lead form; demo/trial offers → LP; content/webinar → form.
+
+## Advantage+ transition
+
+Manual is where you learn; Advantage+ is where you earn. Transition a campaign to Advantage+ only after: a proven offer, a validated audience, and **~50 conversions/week** on the optimization event (the learning-phase exit bar — budget needed ≈ target CPA × 50 ÷ 7 per day). If you can't hit 50/week on the target event, optimize a higher-volume event up-funnel and retarget converters. Advantage+ conflicts with strict ABM (you can't lock it to a list) — see the [ABM playbook](abm-playbook.md). Watch Campaign Score directionally (70+ healthy, <50 = fighting the algorithm) but never trade lead quality for score.
+
+## Benchmarks and seasonality
+
+B2B SaaS Meta ranges (practitioner-reported; recalibrate on your own first 30 days): CTR 1.0–1.5% (red flag <0.8%); CPM $10–20 (red flag >$25); CPL (form) $20–50 (red flag >$75); landing page CVR 8–12%. Seasonality: Q1 CPMs are the year's lowest (scale aggressively); Q4 runs +60–80% (consider reducing B2B spend and banking budget for January).
+
+---
+
+*Framework lineage: this decision system is adapted (re-expressed, reconciled, and restructured) from practitioner operating systems, notably Ivan Falco's ads-skills. All thresholds are starting points — recalibrate against your own account.*

package/departments/marketing/skills/paid-campaign/references/platform-setup-checklists.md

@@ -0,0 +1,277 @@
+# Platform Setup Checklists
+
+Complete setup checklists for major ad platforms.
+
+## Contents
+- Google Ads Setup (Account Foundation, Conversion Tracking, Analytics Integration, Audience Setup, Campaign Readiness, Ad Extensions, Brand Protection)
+- Meta Ads Setup (Business Manager Foundation, Pixel & Tracking, Domain & Aggregated Events, Audience Setup, Catalog, Creative Assets, Compliance)
+- LinkedIn Ads Setup (Campaign Manager Foundation, Insight Tag & Tracking, Audience Setup, Lead Gen Forms, Document Ads, Creative Assets, Budget Considerations)
+- Twitter/X Ads Setup (Account Foundation, Tracking, Audience Setup, Creative)
+- TikTok Ads Setup (Account Foundation, Pixel & Tracking, Audience Setup, Creative)
+- Universal Pre-Launch Checklist
+
+## Google Ads Setup
+
+### Account Foundation
+
+- [ ] Google Ads account created and verified
+- [ ] Billing information added
+- [ ] Time zone and currency set correctly
+- [ ] Account access granted to team members
+
+### Conversion Tracking
+
+- [ ] Google tag installed on all pages
+- [ ] Conversion actions created (purchase, lead, signup)
+- [ ] Conversion values assigned (if applicable)
+- [ ] Enhanced conversions enabled
+- [ ] Test conversions firing correctly
+- [ ] Import conversions from GA4 (optional)
+
+### Analytics Integration
+
+- [ ] Google Analytics 4 linked
+- [ ] Auto-tagging enabled
+- [ ] GA4 audiences available in Google Ads
+- [ ] Cross-domain tracking set up (if multiple domains)
+
+### Audience Setup
+
+- [ ] Remarketing tag verified
+- [ ] Website visitor audiences created:
+  - All visitors (180 days)
+  - Key page visitors (pricing, demo, features)
+  - Converters (for exclusion)
+- [ ] Customer match lists uploaded
+- [ ] Similar audiences enabled
+
+### Campaign Readiness
+
+- [ ] Negative keyword lists created:
+  - Universal negatives (free, jobs, careers, reviews, complaints)
+  - Competitor negatives (if needed)
+  - Irrelevant industry terms
+- [ ] Location targeting set (include/exclude)
+- [ ] Language targeting set
+- [ ] Ad schedule configured (if B2B, business hours)
+- [ ] Device bid adjustments considered
+
+### Ad Extensions
+
+- [ ] Sitelinks (4-6 relevant pages)
+- [ ] Callouts (key benefits, offers)
+- [ ] Structured snippets (features, types, services)
+- [ ] Call extension (if phone leads valuable)
+- [ ] Lead form extension (if using)
+- [ ] Price extensions (if applicable)
+- [ ] Image extensions (where available)
+
+### Brand Protection
+
+- [ ] Brand campaign running (protect branded terms)
+- [ ] Competitor campaigns considered
+- [ ] Brand terms in negative lists for non-brand campaigns
+
+---
+
+## Meta Ads Setup
+
+### Business Manager Foundation
+
+- [ ] Business Manager created
+- [ ] Business verified (if running certain ad types)
+- [ ] Ad account created within Business Manager
+- [ ] Payment method added
+- [ ] Team access configured with proper roles
+
+### Pixel & Tracking
+
+- [ ] Meta Pixel installed on all pages
+- [ ] Standard events configured:
+  - PageView (automatic)
+  - ViewContent (product/feature pages)
+  - Lead (form submissions)
+  - Purchase (conversions)
+  - AddToCart (if e-commerce)
+  - InitiateCheckout (if e-commerce)
+- [ ] Conversions API (CAPI) set up for server-side tracking
+- [ ] Event Match Quality score > 6
+- [ ] Test events in Events Manager
+
+### Domain & Aggregated Events
+
+- [ ] Domain verified in Business Manager
+- [ ] Aggregated Event Measurement configured
+- [ ] Top 8 events prioritized in order of importance
+- [ ] Web events prioritized for iOS 14+ tracking
+
+### Audience Setup
+
+- [ ] Custom audiences created:
+  - Website visitors (all, 30/60/90/180 days)
+  - Key page visitors
+  - Video viewers (25%, 50%, 75%, 95%)
+  - Page/Instagram engagers
+  - Customer list uploaded
+- [ ] Lookalike audiences created (1%, 1-3%)
+- [ ] Saved audiences for common targeting
+
+### Catalog (E-commerce)
+
+- [ ] Product catalog connected
+- [ ] Product feed updating correctly
+- [ ] Catalog sales campaigns enabled
+- [ ] Dynamic product ads configured
+
+### Creative Assets
+
+- [ ] Images in correct sizes:
+  - Feed: 1080x1080 (1:1)
+  - Stories/Reels: 1080x1920 (9:16)
+  - Landscape: 1200x628 (1.91:1)
+- [ ] Videos in correct formats
+- [ ] Ad copy variations ready
+- [ ] UTM parameters in all destination URLs
+
+### Compliance
+
+- [ ] Special Ad Categories declared (if housing, credit, employment, politics)
+- [ ] Landing page complies with Meta policies
+- [ ] No prohibited content in ads
+
+---
+
+## LinkedIn Ads Setup
+
+### Campaign Manager Foundation
+
+- [ ] Campaign Manager account created
+- [ ] Company Page connected
+- [ ] Billing information added
+- [ ] Team access configured
+
+### Insight Tag & Tracking
+
+- [ ] LinkedIn Insight Tag installed on all pages
+- [ ] Tag verified and firing
+- [ ] Conversion tracking configured:
+  - URL-based conversions
+  - Event-specific conversions
+- [ ] Conversion values set (if applicable)
+
+### Audience Setup
+
+- [ ] Matched Audiences created:
+  - Website retargeting audiences
+  - Company list uploaded (for ABM)
+  - Contact list uploaded
+- [ ] Lookalike audiences created
+- [ ] Saved audiences for common targeting
+
+### Lead Gen Forms (if using)
+
+- [ ] Lead gen form templates created
+- [ ] Form fields selected (minimize for conversion)
+- [ ] Privacy policy URL added
+- [ ] Thank you message configured
+- [ ] CRM integration set up (or CSV export process)
+
+### Document Ads (if using)
+
+- [ ] Documents uploaded (PDF, PowerPoint)
+- [ ] Gating configured (full gate or preview)
+- [ ] Lead gen form connected
+
+### Creative Assets
+
+- [ ] Single image ads: 1200x627 (1.91:1) or 1080x1080 (1:1)
+- [ ] Carousel images ready
+- [ ] Video specs met (if using)
+- [ ] Ad copy within character limits:
+  - Intro text: 600 max, 150 recommended
+  - Headline: 200 max, 70 recommended
+
+### Budget Considerations
+
+- [ ] Budget realistic for LinkedIn CPCs ($8-15+ typical)
+- [ ] Audience size validated (50K+ recommended)
+- [ ] Daily vs. lifetime budget decided
+- [ ] Bid strategy selected
+
+---
+
+## Twitter/X Ads Setup
+
+### Account Foundation
+
+- [ ] Ads account created
+- [ ] Payment method added
+- [ ] Account verified (if required)
+
+### Tracking
+
+- [ ] Twitter Pixel installed
+- [ ] Conversion events created
+- [ ] Website tag verified
+
+### Audience Setup
+
+- [ ] Tailored audiences created:
+  - Website visitors
+  - Customer lists
+- [ ] Follower lookalikes identified
+- [ ] Interest and keyword targets researched
+
+### Creative
+
+- [ ] Tweet copy within 280 characters
+- [ ] Images: 1200x675 (1.91:1) or 1200x1200 (1:1)
+- [ ] Video specs met (if using)
+- [ ] Cards configured (website, app, etc.)
+
+---
+
+## TikTok Ads Setup
+
+### Account Foundation
+
+- [ ] TikTok Ads Manager account created
+- [ ] Business verification completed
+- [ ] Payment method added
+
+### Pixel & Tracking
+
+- [ ] TikTok Pixel installed
+- [ ] Events configured (ViewContent, Purchase, etc.)
+- [ ] Events API set up (recommended)
+
+### Audience Setup
+
+- [ ] Custom audiences created
+- [ ] Lookalike audiences created
+- [ ] Interest categories identified
+
+### Creative
+
+- [ ] Vertical video (9:16) ready
+- [ ] Native-feeling content (not too polished)
+- [ ] First 3 seconds are compelling hooks
+- [ ] Captions added (most watch without sound)
+- [ ] Music/sounds selected (licensed if needed)
+
+---
+
+## Universal Pre-Launch Checklist
+
+Before launching any campaign:
+
+- [ ] Conversion tracking tested with real conversion
+- [ ] Landing page loads fast (<3 sec)
+- [ ] Landing page mobile-friendly
+- [ ] UTM parameters working
+- [ ] Budget set correctly (daily vs. lifetime)
+- [ ] Start/end dates correct
+- [ ] Targeting matches intended audience
+- [ ] Ad creative approved
+- [ ] Team notified of launch
+- [ ] Reporting dashboard ready

package/departments/marketing/skills/paid-campaign/references/rsa-output-spec.md

@@ -0,0 +1,88 @@
+# Google RSA Output Spec
+
+When the user requests Google Ads RSAs (Responsive Search Ads), output MUST comply with these platform limits and structural requirements. Do not output any RSA that violates them.
+
+## Hard limits per RSA (enforce before responding)
+
+- **Headlines:** exactly **15** per RSA, each **≤ 30 characters** (count characters, including spaces). Render as `1. ... (NN chars)` so the reader can verify.
+- **Descriptions:** exactly **4** per RSA, each **≤ 90 characters**.
+- **Paths:** up to 2 path fields, each **≤ 15 characters**.
+- **Final URL:** present, https.
+- **Pinning:** state any pinned positions explicitly. Default = unpinned unless user asks.
+- **Per-account guardrail:** Google enforces **3 RSAs max per ad group**. When the user asks for >3, group them by ad group.
+
+## Required sidecar artifacts (always include with RSA request)
+
+1. **Ad group structure**, labeled `Ad group structure:` — list each ad group with its theme, target keywords (match types), and which RSAs map to it.
+2. **Negative keyword list**, labeled `Negative keywords:` — minimum **8** entries, group-level vs campaign-level called out.
+3. **Sitelinks** (≥ 4), **Callouts** (≥ 4 ≤25 chars), **Structured snippets** if relevant.
+
+## Medical / CFM compliance (when product context indicates pt-BR medical practice)
+
+If `.agents/product-marketing.md` indicates a Brazilian medical practice (CFM-regulated), the following terms are **forbidden** in headlines, descriptions, sitelinks, and callouts:
+
+- Superlatives: `#1`, `melhor`, `o melhor`, `melhor do brasil`, `top`, `referência`
+- Outcome promises: `garantido`, `garantia`, `cura`, `cura definitiva`, `100%`, `resultado garantido`, `livre da dor`
+- Comparative claims vs other doctors/clinics
+
+Use neutral framing: `atendimento`, `consulta`, `avaliação`, `segunda opinião`, `agende sua consulta`, `tire suas dúvidas`. Geo modifier (`Porto Alegre`, `POA`, `Zona Sul POA`) required where the prompt specifies a region.
+
+## Output ORDER (mandatory — emit in this order to avoid truncation)
+
+1. **Ad group structure** (short)
+2. **Negative keywords** (≥8, MANDATORY — emit BEFORE RSAs so it isn't dropped if output runs long)
+3. **Sitelinks** (≥4)
+4. **Callouts** (≥4)
+5. **RSA1, RSA2, RSA3** (largest section, last — safe to truncate gracefully)
+
+## Output template (mandatory shape)
+
+```
+Ad group structure:
+- AG1 [theme]: keywords (match types) → RSA1, RSA2
+- AG2 [theme]: ...
+
+Negative keywords:
+  Campaign-level:
+    - <kw>
+    - <kw>
+    (≥4 here)
+  Ad-group level:
+    - AG1: <kw>, <kw>
+    - AG2: <kw>, <kw>
+    (≥4 more here — TOTAL ≥8 entries)
+
+Sitelinks (≥4):
+  - <title (≤25)> | <desc1 (≤35)> | <desc2 (≤35)> | URL
+
+Callouts (≥4, each ≤25 chars):
+  - <callout>
+
+RSA1 — [ad group name]
+  Final URL: https://...
+  Path1: ...   Path2: ...
+  Headlines (15, each ≤30 chars):
+    1. <headline> (NN chars)
+    ...
+    15. <headline> (NN chars)
+  Descriptions (4, each ≤90 chars):
+    1. <description> (NN chars)
+    ...
+    4. <description> (NN chars)
+  Pinning: H1=none; H2=none; ...   (or explicit pins)
+
+RSA2 — ...
+RSA3 — ...
+```
+
+## Self-check before responding
+
+Before sending the output, run this checklist mentally:
+
+- [ ] Each RSA has exactly 15 headlines, exactly 4 descriptions.
+- [ ] Every headline is ≤30 chars; every description is ≤90 chars. Character counts printed.
+- [ ] Negative keyword list labeled and ≥8 entries.
+- [ ] Ad group structure labeled.
+- [ ] If medical (CFM): no forbidden superlative/outcome words; geo modifier present where required; language is pt-BR.
+
+If any check fails, rewrite before responding. Do not ship partial RSAs.

package/departments/marketing/skills/product-marketing/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: mkt/product-marketing
+description: >
+  Create and maintain the product marketing context document — the
+  shared positioning, ICP, and messaging file that every other marketing
+  skill reads first. TRIGGER: "product context", "marketing context",
+  "positioning", "quem é o meu público-alvo", "ICP", "ideal customer
+  profile", "define o produto", "set up context", "/mkt product-marketing".
+  Run this at the start of any new marketing engagement before the other
+  skills. SKIP: buyer/user persona depth as a research artifact ->
+  kb/persona-build (this captures positioning context, that builds a
+  persona); competitor teardown -> mkt/competitor-analysis; brand voice
+  system as a standalone deliverable -> brand/voice-guide.
+allowed-tools: [Read, Write, Edit, Grep, Glob, Agent]
+metadata:
+  origin: community
+  source: https://github.com/coreyhaines31/marketingskills
+  license: MIT
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# Product Marketing Context — `/mkt product-marketing`
+
+> **Agent:** Lourenço (Product Marketing Manager) | **Frameworks:** Obviously Awesome (Dunford), JTBD Four Forces, Schwartz 5 Levels
+
+You create and maintain the **product marketing context document** — the
+foundational positioning and messaging file that every other marketing
+skill reads before it acts, so the user never repeats product, audience,
+or positioning basics across tasks.
+
+## Where the context lives (the ArkaOS contract)
+
+This is the standard **Context block** every marketing skill in ArkaOS
+opens with. Resolution order:
+
+1. **Canonical (KB-first):** the Obsidian note
+   `WizardingCode/Marketing/product-marketing.md`. Read it via
+   `mcp__obsidian__read_note` / `mcp__obsidian__search_notes`.
+2. **Project-local fallback:** `.agents/product-marketing.md` in the
+   working repo (and the legacy `.claude/product-marketing.md` /
+   `product-marketing-context.md` names — offer to migrate to the
+   canonical Obsidian note if found).
+3. **Missing:** offer to build it now with this skill.
+
+When you save, write BOTH: the Obsidian note is the source of truth; a
+project-local `.agents/product-marketing.md` copy stays in the repo the
+work targets so tool-only sessions without vault access still resolve it.
+
+## Workflow
+
+### Step 1 — Check for existing context
+
+Check the Obsidian note first, then the project-local fallbacks. **If it
+exists:** read it, summarize what is captured, note the current
+**Document version** and the last few **Changelog** entries, ask which
+sections to update, and only gather for those. On any substantive save,
+bump the version and prepend a changelog entry (Step 4).
+
+**If it does not exist, offer two paths:**
+
+1. **Auto-draft from the codebase / vault** (recommended): study the
+   repo (README, landing pages, marketing copy, `package.json`) and any
+   existing Obsidian notes on the product, draft a V1, then ask "What
+   needs correcting? What's missing?"
+2. **From scratch:** walk each section conversationally, one at a time.
+
+### Step 2 — Gather information
+
+Push for **verbatim customer language** — exact phrases beat polished
+descriptions because copy resonates when it mirrors how customers
+actually speak. Draft or ask one section at a time; confirm before
+moving on.
+
+## Sections to capture
+
+1. **Product Overview** — one-liner, what it does, product category (the
+   "shelf" customers search on), product type, business model & pricing.
+2. **Target Audience** — company type, decision-makers, primary use case,
+   jobs-to-be-done, specific scenarios.
+3. **Personas (B2B)** — for each stakeholder (User, Champion, Decision
+   Maker, Financial Buyer, Technical Influencer): what they care about,
+   their challenge, the value promised.
+4. **Problems & Pain Points** — core challenge before finding you, why
+   current solutions fall short, what it costs (time/money/opportunity),
+   emotional tension.
+5. **Competitive Landscape** — direct (same solution/problem), secondary
+   (different solution/same problem), indirect (conflicting approach);
+   how each falls short.
+6. **Differentiation** — capabilities alternatives lack, how you solve it
+   differently, why that is better, why customers choose you.
+7. **Objections & Anti-Personas** — top 3 sales objections + responses;
+   who is NOT a fit.
+8. **Switching Dynamics (JTBD Four Forces)** — Push, Pull, Habit, Anxiety.
+9. **Customer Language** — verbatim problem/solution phrasing, words to
+   use, words to avoid, glossary.
+10. **Brand Voice** — tone, communication style, 3–5 personality
+    adjectives (align with `brand/voice-guide` if one exists).
+11. **Proof Points** — metrics/results, notable customers, testimonial
+    snippets, value themes + evidence.
+12. **Goals** — primary business goal, key conversion action, current
+    metrics.
+
+### Step 3 — Create the document
+
+Write the note with versioned frontmatter and the 12 sections above,
+ending with a **Changelog** (newest first, one line per revision). Use
+the section templates (tables for Personas / Objections / Glossary /
+Proof themes) so downstream skills can parse it.
+
+### Step 4 — Confirm, version, save
+
+- Show the completed document; ask what to adjust.
+- **New document:** `Document version: v1` + one changelog entry
+  `- v1 (YYYY-MM-DD) — Initial context.`
+- **Update:** increment the version, set `Last updated` to today,
+  **prepend** a changelog entry naming the sections touched and the
+  reason (never rewrite past entries). Typo-only fixes do not bump.
+- Save to the Obsidian canonical note AND the project-local
+  `.agents/product-marketing.md`.
+- Tell the user: "Every other `/mkt`, `/landing`, `/saas`, and `/sales`
+  marketing skill now reads this context automatically. Run
+  `/mkt product-marketing` anytime to update it."
+
+## Output → Obsidian
+
+`WizardingCode/Marketing/product-marketing.md` (canonical) + project-local
+`.agents/product-marketing.md` mirror.
+
+## Related ArkaOS skills
+
+- **mkt/marketing-plan** — turns this context into a 12-month AARRR plan.
+- **mkt/competitor-analysis** — deepens section 5.
+- **landing/copy-framework**, **landing/optimize-page** —
+  all read this context before generating copy.
+- **kb/persona-build** — builds a full research persona from the ICP here.