viral-product-evaluator v1.4.1A

Immutable. This exact content never changes and is served at /api/v1/blob/2ca272f1eb4c4221.

---
name: "viral-product-evaluator"
description: "Review a product codebase and landing page against 32 viral principles and produce a Virality Score plus ranked fixes. Use to audit virality or prioritize growth. Don't use for SEO, ASO, copywriting, or code review."
license: MIT
effort: high
metadata:
  version: 1.4.1
  author: "Luong NGUYEN <luongnv89@gmail.com>"
---

# Viral Product Evaluator

Grade a product against the 32 principles of viral products. Two inputs — a **codebase** and a
**landing page** — produce one output: a scored report of **what's already satisfied** and, in
**priority order, what to do next to make it more viral**.

## When to Use

Trigger when the user wants to:
- Make a product, SaaS, or indie app "more viral" or more shareable
- Score / audit a landing page against viral-marketing or conversion principles
- Get a prioritized, ordered list of changes to improve a product's pull
- Check a product against "the 32 principles" (Marc Lou-style viral-product rules)

Do **not** use for: technical SEO (`seo-ai-optimizer`), App Store ASO (`aso-marketing`),
turning a README into a page (`landing-page-generator`), or bug-hunting code review
(`code-review`). This skill
**evaluates and prioritizes**; it does not rewrite the product.

## Prerequisites

- Read access to the target codebase directory.
- Landing page signal: public URL, local file, or auto-detectable in the tree.
- The skill's `references/*.md` files present for the rubric and output shape.

Missing prerequisites → stop and report before gathering evidence.

## What this skill does and does not touch

It **reads** the codebase, **fetches** the landing page, and **writes one report file**
(`viral-evaluation.md`). It does **not** edit the user's source, change copy, or commit
anything — so no repo-sync/branch guardrail is needed. If the user then asks you to *apply*
fixes, that is a separate task (hand off to a copy/frontend skill); this skill stops at the
prioritized plan.

## Dependency Preflight (mandatory)

This skill invokes `/browse`, and only on the **live URL** path — a local file or an
auto-detected page needs nothing installed. Resolve it before fetching anything:

```bash
test -d "$HOME/.claude/skills/browse" || asm list -p claude --json | grep -q '"browse"' || {
  echo "Missing required skill: browse" >&2
  echo "Install it:      asm install github:garrytan/gstack:browse -p claude -s global --yes" >&2
  echo "No asm yet:      npm install -g agent-skill-manager" >&2
  echo "Verify:          asm list -p claude --json | grep 'browse'" >&2
}
```

The install-path test runs first because `/browse` ships in gstack and may be present without
`asm` knowing about it. `-p claude -s global` is required: `asm install` will not guess a provider
non-interactively, and a project-scoped install lands where the `$HOME` test cannot see it.

A missing `/browse` is **fail-soft**, not fatal: print the commands above, then ask the user for a
local file or saved HTML of the page. Never score a URL you could not load — do not invent one.

## Inputs

Accept any combination the user provides; ask only for what's missing and truly needed.

1. **Landing page** — one of:
   - a **live URL** → fetch it with the `/browse` skill (headless). Capture rendered copy,
     headline, CTAs, pricing section, testimonials, nav, and `<head>` meta (`og:image`,
     `twitter:image`, `description`, `<title>`).
   - a **local file** (`index.html`, a JSX/TSX/MDX page, a built `dist/`) → read it directly.
   - **auto-detect** from the codebase → search for the landing/marketing page (common spots:
     `index.html`, `app/page.tsx`, `pages/index.*`, `src/App.*`, `landing/`, `marketing/`,
     `public/`). Confirm the candidate with the user if ambiguous.
2. **Codebase** — a path to the repo (defaults to the current working directory). Used for the
   pricing/paywall/subscription principles, the feature surface ("does one thing"), and to
   locate the landing page if no URL/file was given.
3. **Extra instructions** (optional) — strategic context such as "we keep a free tier on
   purpose", "target audience is developers", "we must stay subscription". Honor these when
   *interpreting* a verdict (note the deliberate deviation) but still score the principle as
   written so the number stays comparable.

If neither a URL, a file, nor a detectable page exists, stop and ask the user where the landing
page lives — do not invent one.

## Pipeline (3 phases, in order)

Run these in sequence. Emit the matching Step Completion Report (see
`references/step-reports.md`) after each.

### Phase 1 — Resolve inputs & gather evidence

- Resolve the landing page input (URL → `/browse`; file → read; else auto-detect).
- Locate the codebase and find **monetization evidence**: billing SDKs (Stripe, Paddle,
  LemonSqueezy, RevenueCat, Chargebee), pricing config/constants, plan & tier definitions,
  paywall/auth gating, trial logic. Grep for `price`, `plan`, `tier`, `checkout`,
  `subscription`, `free`, `trial`, `stripe`, `paddle`.
- Skim the **feature surface** (routes, nav items, top-level modules) to judge "does one thing".
- For a large codebase, use **grep/read** (or a one-off **Agent** task scoped to pricing +
  feature evidence) so the main context stays clean. Collect: tier list, billing type (one-time
  vs subscription), free-plan yes/no, and a one-line feature inventory.
- Note any extra instructions from the user.

### Phase 2 — Evaluate against the 32 principles

- Read `references/principles.md` — the full rubric. Score **every** principle PASS / PARTIAL /
  FAIL using its criteria. Do not skip any; absence of a thing a viral product would ship
  (pricing, testimonials, demo) is a real **FAIL**, not "unknown".
- For each verdict, capture **specific evidence from THIS product** — quote the actual headline,
  name the actual tier, cite the file/line. Generic findings are not acceptable.
- Tag every `judgment`/`visual` principle (hero punch, emotional headline, OG-image design,
  founder presence, novelty, price-vs-competitor) as **low-confidence** and record what a human
  must eyeball.
- Compute the **Virality Score** with `scripts/virality_score.py`: pass every verdict as
  `{"verdicts": {"<principle number>": "PASS|PARTIAL|FAIL", ...}}` and use the helper's
  `counts`, `score`, and `tier` (contract in `references/principles.md` → Scoring). Do not
  tally or round in prose.

### Phase 3 — Prioritize fixes & write the report

- Read `references/report-template.md` and produce the report in that exact shape:
  **verdict block → scorecard (all 32) → top fixes (prioritized) → what's working → caveats**.
- The **top fixes** list is the core deliverable. Order by **impact × ease**, hero/paywall/
  headline/proof/single-CTA first. Merge principles that share a root cause into one fix. Make
  each fix concrete enough to act on (give the actual proposed headline, the tier to cut, the
  CTA label) — quote what it is **Now** and what to **Change** it to.
- Always write the report to `viral-evaluation.md` — repo root, or the current working directory
  when there is no repo — and also print the verdict block + top fixes inline.

## Honest evaluation

This is a critique tool — its value is candor. Do not inflate scores to be encouraging. If the
hero fails, say it fails and show the fix. At the same time, do not invent flaws: a genuine PASS
is a PASS. Low-confidence verdicts must be labeled, never laundered into false certainty. When
extra instructions justify a deliberate deviation (e.g. a strategic free tier), score the
principle as written and explain the trade-off in the caveats — don't silently pass it.

On any failure to fetch inputs or read evidence, report the concrete error and stop — do not
guess or continue with incomplete data. Confirm with the user before fetching inputs and
before writing `viral-evaluation.md`. If a principle cannot be evidenced, mark FAIL or low-confidence; never invent.

## Step Completion Reports

After each phase, emit the report from `references/step-reports.md`. The three phases are
**Gather Evidence**, **Evaluate**, and **Prioritize & Report**.

## Acceptance Criteria

- All 32 principles scored with specific evidence quoted from the product.
- Virality Score and tier come from `scripts/virality_score.py` over all 32 verdicts
  (PASS=1, PARTIAL=0.5, FAIL=0); per-principle verdicts and evidence remain model-owned.
- Top fixes are concrete, prioritized by impact×ease, with before/after suggestions.
- Report always written to viral-evaluation.md (repo root, else the current working directory) and
  also printed inline; Step Completion Reports emitted per phase.
- Negative-trigger domains respected (no SEO/ASO/copy/code-review work).

## Expected output

A report containing:
- Overall verdict + Virality Score (e.g. 68 — Promising)
- Scorecard table for all 32 principles
- Top 5-8 prioritized fixes with exact copy or code recommendations
- What's already working
- Caveats / low-confidence items

## Edge cases

- No landing page detectable: ask for URL or file; do not fabricate.
- Codebase only (no public page): still score what can be inferred from code (pricing etc).
- Strategic deviation justified by user (e.g. no testimonials by design): score as written, note the trade-off in caveats.
- Partial evidence: mark affected principles low-confidence, never guess a PASS.

---

## Reference files

- `references/principles.md` — the 32-principle rubric: per-principle checks, evidence source,
  PASS/PARTIAL/FAIL bars, confidence flags, and the `scripts/virality_score.py` scoring
  contract. **Load every run.**
- `references/report-template.md` — exact output shape (verdict block, scorecard, prioritized
  fixes, strengths, caveats) with a calibration example.
- `references/step-reports.md` — Step Completion Report formats for the three phases.
- `scripts/virality_score.py` — deterministic Virality Score + tier helper (`tests/` holds its
  stdlib fixtures).