@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/plan-docs-sync/references/output-templates.md

@@ -0,0 +1,33 @@
+# Output Templates
+
+## Drift counts
+
+| Type | Count |
+|------|-------|
+| stale | … |
+| missing | … |
+| phantom | … |
+| contradictory | … |
+| onboarding-breaking | … |
+| inline-rot | … |
+| api-contract | … |
+
+## Per-doc inventory
+
+| Doc | Section | Drift type | Audited |
+|-----|---------|------------|---------|
+
+## Burndown
+
+| Doc location | Claim | Drift type | Code truth (path:line) | Severity | Effort | Proposed fix | Risk |
+
+P0 = onboarding-breaking or misleading security/setup · P3 = minor wording
+
+## Phased sync plan
+
+1. Onboarding-breaking + misleading-security docs
+2. Phantom + contradictory
+3. Missing docs for shipped features
+4. Inline rot
+
+Each item: before/after grounded in cited code + "what's still accurate here"

package/skills/plan-docs-sync/references/preservation-contract.md

@@ -0,0 +1,17 @@
+# Preservation Contract
+
+Applies to **every phase**.
+
+## Never do in this pass
+
+- **Fabricate behavior** in proposed corrections. Docs describe what code does *now*, verified against source. Unknown → `[NEEDS VERIFICATION]`.
+- **Guess** codebase facts. Every drift shows doc claim + code fact (path:line).
+- **Delete docs** for features that still exist. Stale → correct, don't drop. Removal → proposal for approval.
+- **Churn accurate prose** for style-only changes. Flag genuine mismatches only.
+- **Pick silently** when two docs disagree — surface both + code truth.
+- **Rewrite docs** in this pass. Corrections are proposed with before/after on approval.
+
+## Buckets
+
+- **Factual drift** — doc ≠ code
+- **Subjective wording improvement** — accurate but could be clearer (lower priority)

package/skills/plan-error-handling/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: plan-error-handling
+description: >
+  Plan-only audit of silent failures and observability gaps (Sentry,
+  Langfuse). Use when "errors aren't showing in Sentry", "things fail
+  silently", or "empty catch blocks". Apply patterns → backend-error-handling.
+license: MIT
+effort: high
+---
+
+# Error-Handling & Observability Audit + Fix Plan
+
+**Degree of freedom: HIGH** — map silent paths, score, plan. Stay
+**plan-only**. No code or SDK edits until each phase is approved.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **plan-error-handling** (this) | Silent-failure + Sentry/Langfuse plan |
+| `debug-sentry-monitor` | Live Sentry triage |
+| `audit-langfuse-llm` | LLM eval / trace quality |
+
+## How to reason (every plan item)
+
+1. **Propose** — report, init, redact, or wrap a silent path
+2. **Risk** — what fails in prod with no signal (or PII leaving the env)
+3. **Keep-working** — surfaces that already capture and sanitize
+4. **Phase** — swallows → coverage → redaction → LLM traces (do not execute)
+
+## Worked example
+
+> **Propose:** report + rethrow the empty catch on `api/pay.ts` charge; init Sentry on the edge surface.
+> **Risk:** payment failures produce no event — you only hear from the user.
+> **Keep-working:** web client already captures unhandled exceptions.
+> **Phase:** Phase 1 — stop silent failures.
+
+**Role:** Senior reliability engineer + observability specialist.
+
+**Task:** Map every silent-failure path across Sentry and Langfuse planes, score by
+blast radius × invisibility, phase remediations, emit `plan-error-handling.md`.
+**Audit & plan only — no code or SDK edits until each phase is approved.**
+
+**Find what fails in silence. Make it observable. Change nothing until approved.**
+
+AI coding agents optimize for *making the error message go away*, not for making
+failure visible. **Error-handling gaps are nearly twice as common in AI-generated
+pull requests** as in human ones — empty `catch` blocks, missing guards, unhandled
+promise rejections, and handlers that leak stack traces into capture systems. The
+dangerous part isn't the crash you see; it's the failure you *don't*.
+
+This skill is the **audit-and-plan** half. Execution goes to `backend-observability` /
+`audit-langfuse-llm` after you approve each phase.
+
+---
+
+## When this fires
+
+Trigger phrases: *"errors don't reach Sentry"*, *"it fails silently"*, *"empty
+catch blocks"*, *"add error handling"*, *"why can't I debug prod"*, *"check my
+Langfuse traces"*, *"my LLM costs are a mystery"*, *"pre-launch observability"*.
+
+Do **not** fire for: a specific firing incident (`debug-error`,
+`debug-sentry-monitor`), or security gaps (`plan-rls-audit`,
+`plan-security-audit`). This is the *coverage* audit, not incident response.
+
+---
+
+## Why a dedicated skill
+
+`plan-stub-checker` finds *fake* functionality (dead buttons). This finds *real*
+functionality that *fails invisibly*. Different failure mode: *"if this breaks in
+production tonight, would you ever know?"*
+
+---
+
+## Plane 1 · Application errors (Sentry)  [HIGH freedom]
+
+Walk every error path:
+
+- **Swallowing catches** — `catch (e) {}`, `catch { return null }`,
+  `catch (e) { console.log(e) }` with no rethrow and no Sentry capture.
+- **Unreported catches** — handlers that *log* but never call
+  `Sentry.captureException`. Local console ≠ production visibility.
+- **Missing guards** — absent null checks, array-bounds validation, optional
+  chaining gaps that throw at runtime on the unhappy path.
+- **Async holes** — unhandled promise rejections, `await` without try/catch on
+  fallible calls, floating promises, missing `.catch()` on fire-and-forget.
+- **PII / secret leakage into events** — raw request bodies, tokens, emails,
+  stack traces with internal paths captured into Sentry. Recommend
+  `beforeSend` scrubbing.
+- **Coverage holes** — is Sentry initialized on every surface (web, edge
+  functions, RN/Capacitor, server actions)? Source maps uploaded?
+- **User-facing vs internal split** — sanitized user message vs raw stack in UI?
+
+## Plane 2 · LLM observability (Langfuse)  [HIGH freedom]
+
+For any AI/LLM feature:
+
+- **Untraced calls** — model/tool/retrieval calls with no `@observe` /
+  Langfuse generation wrapping them.
+- **Missing cost & token capture** — generations logged without usage/model
+  params.
+- **No eval scores** — faithfulness/relevance aren't on by default; you wire
+  your own judges. Flag features shipping with zero quality signal.
+- **Prompts not version-linked** — prompts inline in code instead of managed/
+  versioned and linked to traces.
+- **Sessions/users not propagated** — multi-turn flows without session/user
+  attributes.
+- **PII in traces** — confirm SDK-layer redaction before traces leave the env.
+- **Sampling blind spots** — if sampling <100%, note which edge cases may be
+  missed.
+
+> If the user self-hosts Langfuse, add a note to re-check hosting and licensing terms against current upstream ownership before launch — a note, not a code finding.
+
+## Cross-plane
+
+- **Error ↔ trace correlation** — can a Sentry error tie back to its Langfuse
+  trace (shared request/trace id)?
+- **Structured logging** — JSON + correlation ids vs `console.log` soup?
+
+---
+
+## Procedure  [HIGH freedom]
+
+1. **Inventory surfaces.** Which planes exist (Sentry? Langfuse? both?). Skip absent
+   planes. State assumptions.
+2. **Sweep.** Collect findings with `path:line`. For each: *"If this fails in prod,
+   what's the signal?"* — None / Console-only / Sentry / Langfuse.
+3. **Score.** Severity = blast radius × invisibility.
+4. **Phase** into shippable groups mapped to execution skills.
+5. **Emit `plan-error-handling.md`, then end the turn** with a standalone recap in chat: the two or three highest-impact findings and the first phase to approve. The file is the deliverable — write it before the recap. **Do not edit code.**
+
+---
+
+## Guardrails  [LOW freedom — run exactly]
+
+- **Plan only.** No wrapping, no try/catch insertion, no SDK config edits.
+- **Don't add noise.** Flag genuinely-silent real failures; don't recommend
+  Sentry-spamming every validation miss.
+- **Swallowing ≠ handling.** Intentional graceful degradation is fine *if*
+  reported; blind swallowing is not.
+- **Redaction is not optional.** PII/secret reaching Sentry or Langfuse = High
+  minimum.
+- **Observability ≠ prevention.** Pair with `plan-test-coverage`.
+- **Minimal quoting** of source.
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — every row has `path:line` and today's signal
+2. **plan-only** — no try/catch, wrap, or SDK edit this pass
+3. **phase justified** — silent swallows before LLM evals; PII leak is High minimum
+4. **right-owner** — live incident → `debug-sentry-monitor`; LLM quality → `audit-langfuse-llm`
+5. **no-false-safety** — `console.log` ≠ Sentry; do not spam validation misses
+
+---
+
+## Report template — `plan-error-handling.md`
+
+```markdown
+# Error-Handling & Observability Audit — <repo>
+
+_Audit-only. Nothing changes until each phase is approved._
+
+## Scope
+- Planes: [ ] Sentry  [ ] Langfuse  | Surfaces: web / edge / RN / server actions
+- Assumptions / not inspected: …
+
+## Verdict
+| Plane | Silent failures | PII leaks | Coverage holes |
+|-------|-----------------|-----------|----------------|
+| Sentry   | n | n | n |
+| Langfuse | n | n | n |
+
+## Findings — application errors (Sentry)
+| # | path:line | Pattern | Signal today | Sev | Direction |
+|---|-----------|---------|--------------|-----|-----------|
+| E1 | api/pay.ts:88 | empty catch on charge | none | Crit | report + rethrow, surface to user |
+
+## Findings — LLM observability (Langfuse)
+| # | path:line | Gap | Sev | Direction |
+|---|-----------|-----|-----|-----------|
+| L1 | lib/ai.ts:40 | model call untraced | High | wrap with observe, capture usage |
+
+## Phased burndown
+- **Phase 1 — Stop silent failures** → `backend-observability` — E-tier swallows
+- **Phase 2 — Close coverage holes** → `backend-observability` — init gaps, maps
+- **Phase 3 — Redact PII** → `backend-observability` — beforeSend / SDK redaction
+- **Phase 4 — LLM tracing & evals** → `audit-langfuse-llm` — L-tier items
+
+## Execution handoff
+Approve a phase to run it. Re-run after to confirm failures are now observable.
+```
+
+---
+
+## Chains with
+
+- **Security spine** — observability layer (`plan-error-handling`); complements
+  `plan-test-coverage` (tests prevent; observability reveals).
+- **Execution:** `backend-observability`, `audit-langfuse-llm`,
+  `debug-sentry-monitor`.
+- **Verify:** trigger a controlled failure post-fix; confirm Sentry/Langfuse capture.
+
+> Planned at high effort; executed at the default effort under the approved-plan execution rule (`approved-plan-execution.mdc`), which forbids reward hacking and feature deletion on any model. The plan says *what* is invisible; the rule constrains *how* it's wired.

package/skills/plan-gtm/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: plan-gtm
+description: >
+  Plan-only GTM audit: monetization, positioning, activation funnel, SEO/AEO,
+  distribution, and a founder interview. Use when "GTM", "go-to-market", "get
+  more users", "grow traffic", or "should this be freemium". Execute →
+  workflow-gtm.
+license: MIT
+effort: high
+---
+
+# plan-gtm — Go-to-market audit + interview + plan
+
+**Degree of freedom: MIXED.** Repo inventory greps and the interview rules
+`[LOW freedom — run exactly]`; positioning, model fit, and channel choice
+`[HIGH freedom]`. Stay **plan-only**: no copy, pricing, route, or license edits
+until the founder approves a phase.
+
+**Role:** Growth lead who reads code. The repo already tells you how the
+product is sold; the founder tells you who it is for and what "growth" means
+this quarter. Neither alone is a strategy.
+
+**Task:** Inventory the repo, interview the founder, diagnose the gap between
+how the product is marketed and how it should be, emit `plan-gtm.md` with a
+phased burndown mapped to execution skills. **Change nothing until approved.**
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **plan-gtm** (this) | Strategy: who, why-us, how-paid, which channels, what to measure |
+| `workflow-gtm` | Executes the approved phases in order |
+| `plan-pricing` | Value metric, tiers, price points — after this skill picks the model |
+| `enhance-web-conversion` | Hero, pricing page, upgrade prompts (apply) |
+| `enhance-onboarding` | First-session activation (apply) |
+| `enhance-lifecycle-email` / `enhance-growth-loops` | Nudges and loops (apply) |
+| `docs-launch-kit` / `docs-comparison-pages` | Launch posts; "X vs Y" pages (apply) |
+| `audit-registry-listing` | README / npm / GitHub surface for repo-as-product |
+| `iterate-gtm-weekly` | The weekly loop after Phase 4 |
+| `enhance-web-seo` / `plan-aeo-readiness` | Classic search / AI-engine citation |
+| `audit-analytics` | Whether the funnel is instrumented at all |
+| `plan-aso` | App Store / Play listing (mobile) |
+| `design-prd` | What to build next — not how to sell what exists |
+| `workflow-grilling` | Generic interview; this skill uses its rules on GTM questions |
+
+Do **not** fire for "write the landing page" (→ `enhance-web-landing`) or
+"why is my SEO bad" alone (→ `enhance-web-seo`).
+
+## How to reason (every finding)
+
+1. **Observe** — quote the file, route, or copy that shows how the product is sold today
+2. **Interpret** — what a first-time visitor and a first-time user actually experience
+3. **Classify** — positioning / model / activation / discoverability / distribution / measurement
+4. **Decide** — keep, tune, or switch; one execution skill; one metric that proves it
+
+## Worked example
+
+> **Observe:** `LICENSE` is MIT; `README` hero says "145 skills"; `/pricing`
+> route absent; `posthog.init` in `layout.tsx`; no `activated` event; 3.6k npm
+> downloads, 9 GitHub stars.
+> **Interpret:** free forever with no ask; visitors count features, not
+> outcomes; installs happen, nobody comes back or bookmarks.
+> **Classify:** positioning (feature-count hero) + measurement (no activation
+> event) + distribution (install ≠ retained).
+> **Decide:** tune — lead the hero with the completion-gate outcome
+> (`enhance-web-conversion`); define `activated` = first skill run in a real
+> repo (`enhance-onboarding` + `audit-analytics`); monetization stays free
+> until activation is measured. Metric: activated installs / week.
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — every inventory row cites file:line, a route, or a
+   number the founder supplied; "unmeasured" is written where no number exists
+2. **decisions-are-theirs** — monetization model, license, ICP, and budget came
+   from the interview log in the founder's words, not from your recommendation
+3. **one-metric** — the plan names one north-star and one activation event
+4. **two-channels-max** — no plan lists five channels; each carries its caveat
+5. **plan-only** — no copy, pricing, route, robots, or license edits
+6. **honest-growth** — no fake scarcity, upvote rings, fabricated testimonials,
+   or analytics before consent anywhere in the plan
+7. **right-owner** — each phase hands to exactly one execution skill
+
+---
+
+## Step A — Repo inventory  [LOW freedom — run exactly]
+
+Grep before you ask. Record evidence per row.
+
+| Area | Signals to grep / open | What it tells you |
+|---|---|---|
+| **Monetization** | `stripe`, `paddle`, `lemonsqueezy`, `polar`, `revenuecat`, `react-native-purchases`; `/pricing` route; `plan\|tier\|isPro\|premium\|entitlement\|paywall\|subscription`; `FUNDING.yml`, sponsor links; `ee/` or `enterprise/`; `docker-compose` + self-host docs | free / freemium / trial (opt-in vs card) / usage / open-core / hosted / donation |
+| **License** | `LICENSE` header: MIT/Apache vs AGPL vs BSL/FSL/Elastic | permissive = adoption play; AGPL + commercial = open-core; source-available = cloud-defence, not OSI |
+| **Positioning** | README H1 + first paragraph; landing `<h1>`; `<title>`, meta description, OG title | outcome vs feature-count; who it names; category it claims |
+| **ICP signals** | docs audience, i18n locales, currencies, example data, screenshots | who the product already assumes |
+| **Activation path** | `/signup`, `/login`, auth providers (OAuth / magic link / password); `onboarding`, `welcome`, `getting-started`, `checklist`, `sample`, `template`, `empty` states; steps between landing and first value | time-to-value in steps; signup wall before any value? |
+| **Analytics** | `posthog`, `@amplitude`, `mixpanel`, `gtag`, `plausible`, `umami`, `@vercel/analytics`; `track(`, `capture(`; consent banner | is Visit→Signup→Activated→Paid measurable; consent-gated? |
+| **SEO / AEO** | `robots.txt`, `sitemap*`, `llms.txt`, per-page title/description, JSON-LD, canonical, `/blog`, `/docs`, comparison pages | can search and answer engines find and cite it (baseline only — deep audit is `enhance-web-seo` / `plan-aeo-readiness`) |
+| **Distribution assets** | README badges/hero image, `CHANGELOG.md`, `publishConfig` / PyPI, GitHub topics + stars, Product Hunt / HN / awesome-list links, newsletter, Discord/Slack, social handles | where it is already listed; what a share looks like |
+| **Trust** | testimonials, logos, security/privacy/terms pages, status page, real screenshots | why a stranger would believe the claim |
+| **Numbers** | npm/PyPI downloads, stars, store installs, analytics dashboards | fill in; otherwise write **unmeasured** |
+
+Output an **Inventory table** — `Area | Current state | Evidence | Gap?`.
+
+## Step B — Founder interview  [LOW freedom — rules; HIGH freedom — depth]
+
+Rules from `workflow-grilling`: **one question per turn**, **recommend an
+answer with each**, **facts from the repo are never asked**, **log decisions
+in the founder's words**. Walk the ladder in order; skip rungs the inventory
+already answered.
+
+1. **90-day goal metric** — recommend: activated users per week (pre-revenue)
+   or MRR (post-revenue). Not stars, not upvotes.
+2. **Who exactly** — role + situation + what they use today instead. Recommend
+   the ICP the inventory implies.
+3. **Current numbers and channels** — visits, signups, activation, paid,
+   where the last spike came from. Ask for the dashboard or CSV.
+4. **Monetization intent** — stay free / freemium / trial / usage / open-core
+   / hosted. Recommend from the model-fit table below; the choice is theirs.
+5. **Budget** — hours per week and money per month for growth work.
+6. **Geography and language** — which market first (e.g. JP vs EN).
+7. **Alternatives** — the three things a buyer compares against.
+8. **Constraints** — brand, legal, store policy, team, "never do X".
+
+Stop when the plan can be written. Close with the **decision log**. If the
+signup form has no "how did you hear about us" field, propose one in Phase 1
+— it is the cheapest channel attribution that exists.
+
+## Step C — Diagnose  [HIGH freedom]
+
+### Positioning (Dunford order — do not start at category)
+competitive alternatives → unique attributes → value those attributes enable →
+best-fit customers who care most → market category that makes it obvious.
+Write one sentence: *For [ICP] who [situation], [product] is the [category]
+that [value], unlike [alternative].* The hero, README first line, and meta
+description must all be able to carry it.
+
+### Monetization model fit
+
+Free-to-paid, 2026 (ChartMogul × Kyle Poyar × ProductLed, ~200 self-serve products):
+
+| Model | Good | Great | Fits when | Repo signals |
+|---|---|---|---|---|
+| Freemium | 3–5% | 8–12% | volume + network/viral loop; low marginal cost | free tier limits in code, `isPro` gates |
+| Freemium, ungated (no account to try) | 7–9% | 8–12% | adoption is the goal; value visible in one session | demo mode, sample data, no auth on core route |
+| Free trial, no card | 4–6% | 10–15% | B2B, value needs setup time | `trialEndsAt`, 14-day default |
+| Free trial, card required | 25–35% | 50–60% | intent over volume; ACV justifies friction | Stripe Checkout before app |
+| Reverse trial | 4–6% | 8–12% | not statistically better than the two above | premium-then-downgrade logic |
+| Usage-based / hybrid (credits) | — | — | cost per action (AI, infra); expansion via usage; now 41% of B2B SaaS | metering tables, `credits`, Stripe metered prices |
+| Open-core + hosted cloud | 0.5–2% self-host → paid; cloud carries 48–73% of revenue at public OSS vendors | — | painful to operate; enterprise SSO/RBAC/audit | AGPL + `ee/`, `docker-compose`, cloud signup |
+| Donation / sponsorship | — | — | libraries and CLIs with no hosted surface; rarely sustains alone | `FUNDING.yml`, no billing code |
+| Paid-only | — | — | niche pro tool, strong word of mouth | paywall before any value, no free plan |
+
+Median across all models is 8%; a fifth of products convert under 2.5%.
+"Freemium vs trial" is the wrong question: **adoption → open the product
+before signup; conversion → require a card.** Activation inside the free
+window explains most of the variance — fix activation before changing price.
+Underpricing attracts the curious, not the committed. Never recommend a
+license change as a growth tactic; relicensing cost Elastic and Redis
+contributors and gained no revenue. Full rows and URLs:
+`references/benchmarks-2026.md`.
+
+### Activation and north-star
+Reforge order: **Setup** (must-have info) → **Aha** (core value once) →
+**Habit** (core action at its natural frequency). `activated` is the aha
+event — not signup, not tour end, never payment (that kills it as a leading
+indicator). A valid activation event shows ≥ 2× retention for users who hit
+it; if analytics exist, pick the event combination that best predicts
+3-month retention. Benchmarks: median B2B activation 37% (good = p60, great
+= p80 for the product type); below 20% is a broken first session;
+time-to-value over 24 h collapses activation under 25%; day-7 return ≥ 7% of
+a new cohort is top quartile. Only about a third of PLG companies track
+activation at all — an "unmeasured" cell here is finding #1.
+Map the funnel **Visit → Signup → Activated → Habit → Paid → Refer** with a
+number or **unmeasured** in each cell; group by organization for B2B.
+
+### Channels — pick ≤ 2 primary + 1 loop
+
+| Channel | Best for | Caveat |
+|---|---|---|
+| Show HN | dev tools, OSS, infra | front page = 5–30k visits, 50–400 signups; >10 points only ~11% of posts; runnable thing, no signup wall, sober human-written post, answer every comment for 2 h |
+| Product Hunt | consumer, design-led SaaS | featured rate ~10%; 1–2% visit→signup for B2B; credibility artifact, not acquisition; relaunch per major version |
+| Reddit / niche communities | narrow ICP, B2B | value-first threads; link-only posts die |
+| Content + comparison pages | anything searched | "X vs Y" / "alternatives to" pages took 78% of clicks from 28% of pages in one test; honest, current, unique per page — scaled AI pages are a Google spam-policy hit |
+| AEO / answer engines | anything explained | earned third-party mentions earn ~6.5× more citations than owned pages; llms.txt has zero Search effect but coding assistants read it on docs sites → `plan-aeo-readiness` |
+| Registries & directories | npm/PyPI packages, skills, plugins, extensions | discovery happens in the registry; README first 10 lines are the hero |
+| Community (Discord/GitHub Discussions) | OSS, dev tools | retention and word-of-mouth, slow to start |
+| Loops | all | "powered by" badge (0.5–3% conversion, near-100% exposure), templates users share, referral credit (SaaS referral rate ~4.75%); value before signup lifts referred conversion 2–5× |
+
+Launch is a **cadence**, not an event: every meaningful release gets a post.
+Name one **distribution hypothesis** in the plan — the failure mode is having
+none, not picking the wrong one.
+
+### Onboarding, pricing page, trust
+Note gaps only; the fixes belong to `enhance-onboarding` and
+`enhance-web-conversion`. Copy that reads generated → `plan-antislop`.
+
+### Name the failure mode
+Every finding maps to one: building before validating (43% of shutdowns are
+PMF), generic hero, underpricing, no distribution hypothesis, activation
+untracked or defined as payment, AI-generated content at scale, launching
+once, reverse trial / AI credits as a fix. The list with sources is in
+`references/benchmarks-2026.md`.
+
+## Step D — Emit `plan-gtm.md`, end the turn  [LOW freedom — run exactly]
+
+```markdown
+# GTM Plan — <product>
+
+_Plan-only. Nothing changes until each phase is approved._
+
+## Decision log (founder's words)
+- Goal metric (90 d): …
+- ICP: …
+- Monetization: …
+- Budget: … h/week, … /month
+- Market/language: …
+
+## Inventory verdict
+| Area | Status | Worst gap | Evidence |
+|------|--------|-----------|----------|
+
+## Positioning statement
+For … who …, <product> is the … that …, unlike ….
+
+## Monetization verdict
+keep / tune / switch — why, with the benchmark row it is judged against.
+
+## Activation & north-star
+- `activated` = …   · north-star = …
+| Visit | Signup | Activated | Habit | Paid | Refer |
+|-------|--------|-----------|-------|------|-------|
+| n | n | unmeasured | … | … | … |
+
+## Channel plan (≤2 + loop)
+| Channel | Why this ICP | Caveat | First action |
+
+## Findings
+| # | Area | Gap | Evidence | Sev | Direction |
+
+## Phased burndown
+- **Phase 1 — Measure & message** → `audit-analytics`, `enhance-web-conversion` (hero), `enhance-readme`; repo-as-product adds `audit-registry-listing`
+- **Phase 2 — Activate** → `enhance-onboarding`, `audit-ui-states`, `enhance-web-forms`, `enhance-lifecycle-email` (activation nudges)
+- **Phase 3 — Be found** → `enhance-web-seo`, `plan-aeo-readiness`, `docs-comparison-pages`
+- **Phase 4 — Launch & loop** → `docs-launch-kit`, `enhance-growth-loops`, `iterate-gtm-weekly`
+- **Phase 5 — Monetize** → `plan-pricing` (approve first), `enhance-web-conversion` (pricing, upgrade prompts), `enhance-lifecycle-email` (trial expiry), `audit-payment-system`
+
+## 30 / 60 / 90
+| Day | Metric | Target | Owner skill |
+
+## Weekly GTM review (after Phase 4)
+Funnel by source · activation cohort · top drop-off step · one experiment
+shipped · one launch or post.
+
+## Execution handoff
+Approve a phase → `workflow-gtm` runs it and re-reads the funnel table.
+```
+
+End the turn with a standalone recap in chat: the decision log in one line, the two or three highest-impact findings, and Phase 1's first action. The file is the deliverable — write it before the recap.
+
+## Guardrails
+
+- **Plan only.** Inventory + interview + document.
+- **Unmeasured is a value.** Never invent a conversion rate or traffic number.
+- **No promised outcomes.** Rank, virality, and "10x signups" are not deliverables.
+- **No dark patterns.** No fake scarcity, hidden cancel, confirm-shaming, upvote
+  solicitation, fabricated reviews, or analytics before consent.
+- **Business decisions stay with the founder.** Model, price, license, ICP.
+
+## Chains with
+
+- **`workflow-gtm`** — executes the approved phases.
+- **Growth gate** — pairs with `plan-aeo-readiness`, `plan-aso` in `docs/PLAN-LOOPS.md`.
+- **`audit-analytics`** — run first when the funnel table is all "unmeasured".
+- **`iterate-gtm-weekly`** — the weekly loop after Phase 4 (`iterate-post-launch` keeps production bugs).
+
+> Planned at high effort; executed at the default effort under the approved-plan execution rule (`approved-plan-execution.mdc`), which forbids reward hacking and feature deletion on any model.