Viral Product Evaluator

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

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).

Prerequisites

• Read access to the target codebase directory.
• Landing page signal: public URL, local file, auto-detectable in the tree, or an orchestrator's evidence-dir.
• The skill's references/*.md files present.

Missing prerequisites after the one ask in Edge cases → stop with a BLOCKED response (references/final-report.md) 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 never edits source, changes copy, or commits. Applying fixes is a separate task for a copy/frontend skill; this skill stops at the prioritized plan.

Dependency Preflight (mandatory)

This skill invokes /browse (frontmatter dependencies), and only on the live URL path; every other input needs nothing installed. Run once, before the first fetch:

if test -f "$HOME/.claude/skills/browse/SKILL.md"; then
  echo "browse_mode=installed browse_skill=$HOME/.claude/skills/browse/SKILL.md"
elif test -f "$HOME/.agents/skills/browse/SKILL.md"; then
  echo "browse_mode=installed browse_skill=$HOME/.agents/skills/browse/SKILL.md"
elif command -v asm >/dev/null && asm deps --help >/dev/null 2>&1; then
  asm deps discover viral-product-evaluator --json || echo "discover failed; acquire still runs" >&2
  echo "browse_mode=lease"
else
  echo "Missing skill: browse. Install: asm install github:garrytan/gstack:browse -p claude -s global --yes" >&2
  echo "No asm yet: npm install -g agent-skill-manager@latest" >&2
  echo "browse_mode=none"
fi
printf 'vpe_session=%s\n' "viral-product-evaluator-$(date +%s)-$$"   # record it; reuse it verbatim

The install-path tests run first because gstack may install /browse without asm knowing.

1. browse_mode=installed: read the recorded browse_skill path.
2. browse_mode=lease: run asm deps acquire browse --session <vpe_session> --json; read the returned skillMdPath directly.
3. browse_mode=none, or step 2 failed: fail-soft — print the install lines, then ask the user for a local file or saved HTML of the page. Never score a URL you could not load.
4. Release in finally. If step 2 ran, run asm deps release --session <vpe_session> --json once at every terminal outcome, stops included.

Repo Sync Before Edits (mandatory)

Phase 3 writes viral-evaluation.md. An inline-only run never syncs or stashes a checkout. When the output path is inside a git worktree, follow references/repo-sync.md: confirm with the user, then stash, sync and pop before the write.

Inputs

1. Landing page — resolve in this order:
   • an orchestrator's evidence-dir → read its page.html + head.json; no /browse.
   • a live URL → run the Dependency Preflight, confirm the fetch with the user, then load 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 the common spots (index.html, app/page.tsx, pages/index.*, src/App.*, landing/, marketing/, public/). If exactly one candidate is found, use it. If none or several are found, ask the user.
2. Codebase — a path to the repo (defaults to the current working directory). Used for the pricing/paywall principles, the feature surface, and landing-page auto-detection.
3. Extra instructions (optional) — strategic context such as "we keep a free tier on purpose". Honor these when interpreting a verdict (note the deliberate deviation) but still score the principle as written so the number stays comparable.

Pipeline (3 phases, in order)

Phase 1 — Resolve inputs & gather evidence

1. Resolve the landing page per Inputs.
2. Locate the codebase (default: the current working directory).
3. Grep it for price, plan, tier, checkout, subscription, free, trial, stripe, paddle and read the matches.
4. Record the monetization evidence section A of the rubric lists (references/principles.md). When nothing matches, record "no billing evidence found" — that is itself evidence.
5. Skim routes, nav items and top-level modules; record a one-line feature inventory.
6. When the codebase is too large for the context budget, delegate steps 3–5 to a one-off Agent task scoped to pricing and feature evidence.
7. Note any extra instructions from the user.

Phase 2 — Evaluate against the 32 principles

1. Read references/principles.md — the full rubric.
2. Score every principle PASS / PARTIAL / FAIL; never skip one. Absence of a thing a viral product would ship (pricing, testimonials, demo) is a real FAIL, not "unknown".
3. Quote product-specific evidence for each verdict — the actual headline, the actual tier, the file/line. Generic findings are not acceptable.
4. Tag every judgment/visual principle (hero punch, emotional headline, OG-image design, founder presence, novelty, price-vs-competitor) low-confidence and record what a human must eyeball. When a principle's evidence source was unavailable (no codebase access, a failed fetch), tag it low-confidence as well and say why.
5. Compute the Virality Score with scripts/virality_score.py — pass every verdict as {"verdicts": {"<n>": "PASS|PARTIAL|FAIL", ...}} (contract in references/principles.md → Scoring). Do not tally or round in prose.