@ranimontagna/agent-toolkit 0.1.19 → 0.1.21

package/skills/frontend/design/revenue-centric-design/references/ai-era-differentiation.md

@@ -0,0 +1,57 @@
+# AI-Era Differentiation & Moats
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## Faster building doesn't fix churn — activation does
+**Principle.** Build speed was never the bottleneck. Shipping the same confusing interface faster is just a more efficient route to churn. The real gap is the space between a user entering the product and understanding what to do.
+**Apply when.** Vibe coding is sold to a founder as "the product got cheaper to build," and the team equates speed with progress.
+**The move.** Obsess over activation, not velocity. Attack the three things vibe coding never touches: onboarding, attention hierarchy, and value delivery in the first sessions (TTV). More products now compete for the same user attention, so close the entry-to-understanding gap.
+**Voice.** "Build speed without an obsession for activation is just a more efficient way to reach churn."
+**Source.** [@richardrx · 2026-04-02](https://x.com/richardrx/status/2039685818273378644)
+
+## Same engine, different UX: don't compete on the commodity
+**Principle.** AI turned your codebase into a near-commodity — under the hood ~90% of new tools call the same APIs. Engineering solves the base function; design and packaging are what differentiate and resist copying.
+**Apply when.** Your "engine" is effectively identical to a competitor's and a generic interface is pulling you into a price war.
+**The move.** Win on UX architecture, not the engine. Superior UX (1) removes initial friction → lifts conversion; (2) fits the user's workflow → cuts churn, raises LTV; (3) eases continuous/collaborative use → enables upsell. This builds a differentiator that lowers copy risk and keeps the customer paying.
+**Evidence.** VW Up, Seat Mii, and Skoda Citigo share the exact same platform — chassis, drivetrain, and the identical EA211 engine — yet are designed and packaged for different ICPs (young, pragmatic-utility, reliability).
+**Voice.** "The engine may be identical, but it's the architecture of the user experience that builds your moat."
+**Source.** [@richardrx · 2026-03-03](https://x.com/richardrx/status/2028837448717926518)
+
+## A validated idea is a short-term game — plan the moat
+**Principle.** If your only advantage is the codebase, you've merely built a validated MVP for better-funded competitors to execute. Structural barriers to entry (the moat) are planned, never accidental.
+**Apply when.** Your tech is easy to replicate and the product identity is generic — clones can ship within days.
+**The move.** Plan three deliberate moats: (1) Brand Power — a proprietary visual identity with above-average UX signals less risk and sells perceived safety (conversion); (2) Switching cost via UX — intuitive flows users have internalized make moving to a 20%-cheaper clone costly in productivity (retention); (3) Expansion architecture — internal network effects (invite-to-collaborate) are harder to copy and pull in new users (LTV). Users who perceive a value ecosystem prefer paying more over adapting to a worse, cheaper product.
+**Evidence.** The "Roast My Startup" tool was cloned within a week — copies flooded the timeline — proving a codebase-only edge is no defense.
+**Voice.** "Clones can't copy trust."
+**Source.** [@richardrx · 2026-03-03](https://x.com/richardrx/status/2028777831233114152)
+
+## Design for shrinking attention spans
+**Principle.** Short-form video acts on the brain like a variable-reward slot machine, switching off the attention filter and eroding self-control — leaving users with high anxiety and low focus. If your user's attention keeps shrinking, design must be militarily focused.
+**Apply when.** Building any product whose users are conditioned by infinite short-video feeds (attention economy).
+**The move.** Engineer for the attention limit: (1) drastically reduce cognitive load; (2) direct absolutely toward the target task (conversion); (3) build interfaces that respect the human attention ceiling.
+**Evidence.** An EEG study (Fabiano et al., Frontiers in Human Neuroscience) links short-form-video addiction to reduced frontal-lobe activity and weakened ability to focus.
+**Voice.** "TikTok is the hot dog of social media — hyper-palatable, but nutrient-poor: you consume endlessly and it never nourishes you."
+**Source.** [@richardrx · 2026-02-26](https://x.com/richardrx/status/2026978144343687177)
+
+## Sell the value, not the feature list — and show the product
+**Principle.** AI auto-generates landing pages, but ~90% share the same defects. A generic, inconsistent hero is what loses visitors, not the absence of fancy design.
+**Apply when.** Auditing an AI-generated LP that leans on features and trendy gradients instead of the user's pain.
+**The move.** Fix the three recurring failures: (1) generic, inconsistent aesthetics (every component a different color, purple/green gradients on dark/white); (2) over-indexing on features instead of the value/pain they address; (3) barely showing the actual product. Build the hero to pass the 5-second test — what does this do, why care, what next.
+**Visual.** Supafast's "SaaS Hero Section Formula" — 5 elements with before/after copy: Headline (≤8 words, attack the #1 pain), Subheadline (show the transformation), Primary CTA (specific to outcome), Secondary CTA (low-commitment), Trust Bar (5 logos or one specific number) — `../assets/2025246347587162602__q__1.jpg`
+**Source.** [@richardrx · 2026-02-21](https://x.com/richardrx/status/2025246347587162602)
+
+## Don't let AI-to-Figma-to-code factory technical debt
+**Principle.** A Claude → Figma → Code flow looks like speed but creates two documents that drift out of sync, plus inconsistent components — a maintenance Frankenstein, not velocity.
+**Apply when.** A tool promises round-tripping AI output through the design canvas into code as a shortcut.
+**The move.** Refuse the false shortcut. Without a design system and context, generated components are superficially similar but fundamentally inconsistent (random button padding, off-brand colors, inconsistent UX patterns). Manual tweaks don't flow back to code, so the source of truth reverts to the canvas and the two files desync. For devs it's useless (V0/Lovable already emit code without the full-seat toll); for designers it's a distraction that skips information architecture to spit out a screen fast.
+**Voice.** "A technical-debt factory."
+**Source.** [@richardrx · 2026-02-18](https://x.com/richardrx/status/2024076972565963186)
+
+## Beat the four AI failure modes that make a vibe-coded SaaS feel like a fraud
+**Principle.** When the barrier to entry tends to zero, competition tends to infinity. AI lowered that barrier and amplified Dunning-Kruger — you feel omniscient but lack the base to judge if its output is a solution or wasted time. You shipped code, not a seductive product, and you're diving into a red ocean. Code is no longer the asset — just one ingredient.
+**Apply when.** A "complete SaaS in a weekend" is validated but feels hollow, generic, and clonable by Wednesday.
+**The move.** Fix the four pillars where AI fails: (1) **Generic-product trap** — AI is trained on the internet's average, and average builds nothing extraordinary; escape commoditization by building the only possible tool for an ignored niche (not "CRM for doctors" but "CRM for facial-harmonization clinics" with a `last_toxin_date` field and a 110-day retouch-alert cron). (2) **Value delivery / TTV** — don't ship login → empty dashboard (the 99% default); build an on-ramp to value, an onboarding assistant, not a desert. (3) **Trust / visual confidence** — in a sea of V0/Tailwind templates, aesthetics, personality, and consistency are the last remaining trust proxies; intentional, human-aligned pixels signal authority, build trust, and lower CAC. (4) **Human touch** — cheaper code should buy more time for the memorable details (kind error messages, a 404 that returns the user, business logic that anticipates mistakes, a 200ms confirming micro-interaction) — humans are predictably irrational, full of bias.
+**Evidence.** Johnson & Goldstein (2003), *Science* — a mere "opt-out" default produced +90% organ-donation consent, proving small design choices move behavior.
+**Visual.** The Dunning-Kruger curve — confidence spikes at "Ignorant" (low knowledge), craters at "Cultured," and climbs toward "Expert," with a labeled "confidence gap" — `../assets/2013264068518289753__2.jpg`
+**Voice.** "You can own all the cement in the world, but without the blueprint and structural engineering you're just a pile of gray concrete."
+**Source.** [@richardrx · 2026-01-19](https://x.com/richardrx/status/2013264068518289753)

package/skills/frontend/design/revenue-centric-design/references/behavioral-science-toolkit.md

@@ -0,0 +1,60 @@
+# Behavioral Science & Persuasion
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## You can't un-hear your own product
+**Principle.** Once you know how your product works, that knowledge permanently rewrites your perception — what feels obvious to you is just "tap-tap-tap" to a first-time user. You'll mistake confused users for dumb users.
+**Apply when.** You think onboarding is unnecessary because "the product is simple," or a question your support answers weekly seems already-answered on screen.
+**The move.** This is the curse of knowledge — you can't switch the music off, so collect feedback from people who've never seen the product, without steering or naming things, and watch behavior. Run it continuously: use support/CX as an insight collector (tabulate each issue by %, impact, insight), Clarity/PostHog for heatmaps and session replays, sampled user interviews, and competitor benchmarking.
+**Evidence.** Tapping-vs-listening study: tappers hear the full song in their head; listeners only get the taps. Listeners guessed 3 of 120 songs correctly (2.5%) — far below tappers' expectations.
+**Voice.** "You're humming the whole song in your head; your user only hears 'tap, tap, tap.'"
+**Source.** [@richardrx · 2026-06-04](https://x.com/richardrx/status/2062509937037590997)
+
+## Set the default — it's the most underrated lever in conversion
+**Principle.** The pre-selected option captures the overwhelming majority of choices, because deciding is expensive and the lazy brain takes the easiest path. Smart defaults beat copy persuasion.
+**Apply when.** Any choice the user must make — pricing tier, billing cadence, seat count, notifications, checkout — especially before you spend hours rewriting CTAs.
+**The move.** Exploit status-quo bias plus cognitive-load reduction. Pre-select the mid-tier you want to sell (the default takes 60–80% of choices); default billing to annual to lift contracted MRR without changing price; start the seat selector at your ICP's typical count (anchoring); run a reverse trial where premium is the default and free is the opt-out, so the user must actively give up what they already have. Three rules: defaults must be ethically defensible (checkbox tricks become churn and complaints), smart defaults beat copy, and a default acknowledges the user won't burn energy deciding what's trivial to you.
+**Evidence.** Organ-donor study (Science, 2003): opt-out countries register ~6× more donors than opt-in. Germany (opt-in) ~12% vs Austria (opt-out) ~100% — culture/religion don't explain it; it's a pre-checked box. Richard raised average ticket 60% and saw up to 4× LTV applying this to plan acquisition.
+**Visual.** Bar chart of effective organ-donor consent by country: opt-in nations low (Denmark 4.25%, Germany 12%, UK 17.17%, Netherlands 27.5%) vs opt-out nations ~100% (Austria, France, Hungary, Portugal). — `../assets/2057872036718899256__1.jpg`
+**Voice.** "You can spend the rest of your life optimizing copy, or you can change 5 defaults over the weekend."
+**Source.** [@richardrx · 2026-05-22](https://x.com/richardrx/status/2057872036718899256)
+
+## Reinforce the decision the user just made
+**Principle.** After committing to a choice, people actively seek information that supports it — choice-supportive bias. You can feed that need to make the decision feel right.
+**Apply when.** Right after signup, purchase, or any meaningful commitment, when buyer's remorse or doubt could creep in.
+**The move.** Use choice-supportive bias deliberately: send a strong welcome email with clear next steps so the new user feels embraced and validated in having chosen you. (Analogy: someone joins an EV-lovers group right after buying the car.)
+**Source.** [@richardrx · 2026-04-29](https://x.com/richardrx/status/2049392897598849333)
+
+## Architect for what users fear losing, not just what they gain
+**Principle.** Builders obsess over features (gains), but conversion and retention are cemented by what the user fears losing — the pain of abandoning a built-up ecosystem outweighs the pain of paying a subscription.
+**Apply when.** Designing trials, retention/renewal flows, and offboarding for any product where users accumulate data, history, or workflows.
+**The move.** Exploit loss aversion and sunk cost. Convert with zero risk — let users import real competitor data in shadow mode so they can test without fear. Retain by designing the product to make users build workflows and accumulate history from day 1, so at renewal they weigh the headache of rebuilding from scratch, not the monthly fee. At offboarding, don't add friction — make cancellation easy but the loss tangible (e.g., "You'll instantly lose 41 active automations and 6 months of data").
+**Evidence.** Sunk cost is what keeps many users on certain LLMs — fear of losing your memory/history, even when it could be exported with a copy/paste.
+**Visual.** Hotel-listing UI using scarcity ("Only 2 rooms left") — illustrative example of a loss-framed cue. — `../assets/2028471666297217460__1.jpg`
+**Source.** [@richardrx · 2026-03-02](https://x.com/richardrx/status/2028471666297217460)
+
+## Use precise numbers, not round ones, to signal truth
+**Principle.** Exact figures read as more credible than rounded ones; round numbers signal marketing while specific numbers signal reality.
+**Apply when.** Writing any claim, stat, or social-proof number — landing pages, ads, results, testimonials.
+**The move.** Lean on the precise-number effect: say "526 houses," not "over 500." Nothing about the claim changes except the precision, yet trust rises.
+**Evidence.** Schindler & Yalch (2006), 199 participants, fictional deodorant: claims of "47%" or "53%" longer-lasting were judged ~10% more accurate than the rounded "50%" claim — only the precision changed.
+**Visual.** Real billboard: "LAST YEAR WE SOLD 526 HOMES. YOUR COUSIN SOLD 2. LIST RESPONSIBLY." — the precise number doing the persuasion. — `../assets/2024141244717281514__1.jpg`
+**Voice.** "'526 houses' inspires confidence; 'over 500 houses' signals marketing."
+**Source.** [@richardrx · 2026-02-18](https://x.com/richardrx/status/2024141244717281514)
+
+## Guide the eye — don't give every option equal weight
+**Principle.** The brain uses contrast to make fast decisions (Von Restorff effect). When competing options carry identical visual weight, you create mental friction, decision time rises, and conversion falls. Guiding the user isn't manipulation — it's respect for their time.
+**Apply when.** You have 3 plans, two equally-weighted buttons, or any "democratic" interface where everything looks the same (a common founder error, and a default of AI-generated UIs).
+**The move.** Exploit the Von Restorff effect: make the value-generating option visually dominant and de-emphasize the rest (e.g., a ghost-styled "Cancel" beside a bold, colored primary). If you know your ICP's pains and desires, you have a duty to highlight the highest-value solution. Slow decisions accumulate into a "hard-to-use" perception that becomes churn.
+**Visual.** Good/bad confirm dialog: bad = both buttons same green weight; good = a ghost-text "Cancel" beside a solid red "Delete now," so the primary action stands out. — `../assets/2014317885494059106__1.jpg`
+**Voice.** "If everything grabs attention, NOTHING grabs attention."
+**Source.** [@richardrx · 2026-01-22](https://x.com/richardrx/status/2014317885494059106)
+
+## Cut cognitive load — every choice you remove can lift conversion
+**Principle.** Each extra field, choice, or block of complex text spends the user's mental energy and triggers analysis paralysis. Your product can be complex; your interface doesn't have to be.
+**Apply when.** Checkout, signup, and subscription screens — anywhere the user must decide or input under doubt.
+**The move.** Strip the interface to the essential decision; when options can't be cut, break the flow into smaller steps (e.g., a 4-step checkout). Remember the failure is invisible: users don't complain or open tickets — they close the tab as "silent churn" and your CAC is wasted. Then dogfood your own onboarding as if you were a stranger.
+**Evidence.** Removing 1 checkout field raised conversion 10%. Richard has seen reworked subscription screens lift LTV 200% just by simplifying the decision.
+**Visual.** Mobile checkout labeled "Analysis paralysis": payment options split into smaller stages — advice to break choices into ~4 steps. — `../assets/2013597792447394034__1.jpg`
+**Voice.** "They don't file a support ticket. They just close the tab — and your CAC goes in the trash."
+**Source.** [@richardrx · 2026-01-20](https://x.com/richardrx/status/2013597792447394034)

package/skills/frontend/design/revenue-centric-design/references/churn-and-retention.md

@@ -0,0 +1,66 @@
+# Churn & Retention
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## Churn and payback are one problem, measured in two places
+**Principle.** Churn and payback look like two problems (often with different owners) but are the same one — both decided in the user's first session, in the gap between entering and feeling the product works.
+**Apply when.** You're fixing churn at the cancel screen and chasing cheaper CAC in the ad manager at the same time.
+**The move.** Both are the wrong place — the decision was made earlier. Activation fixes both: shrink TTV and you retain more AND get each customer across the payback line before they vanish. A customer who dies in month 2 with a 4-month payback never closes the account. Caveat: not all churn is activation (price, a bad channel exist) — but before chasing cheaper CAC, count how many customers die before repaying what they cost.
+**Voice.** "A customer who dies before repaying his CAC is a bill you paid and never collected."
+**Source.** [@richardrx · 2026-06-30](https://x.com/richardrx/status/2071931705573748896)
+
+## Switching cost is what turns months of LTV into years
+**Principle.** The same product, designed differently, yields months vs. years of LTV. Switching cost = the effort a user *perceives* in leaving; low switching cost means thin history and an easy exit.
+**Apply when.** Designing for retention/lock-in, or explaining why a useful product still churns.
+**The move.** Engineer switching cost deliberately — a "compound interest" that grows the product's value over time. Five levers: **muscle memory** (Superhuman/Photoshop shortcuts), **mental model** (Mac↔Windows, Gmail labels), **accumulated personalization** (Spotify playlists, home-screen layout), the **vault effect** (iCloud/Drive/years of WhatsApp), and **autopilot/habit** (variable-reward Skinner-box loops). Sunk cost holds them the way it holds an investor in a falling stock; habit can take months to install but is the difference between LTV of months and years.
+**Source.** [@richardrx · 2026-06-23](https://x.com/richardrx/status/2069382946214080985)
+
+## Tell the existing base about upgrades before they want to leave
+**Principle.** Reactive improvement communication is a sneaky churn vector: if you only market new versions to cold traffic to avoid cannibalizing the old product, your base assumes the old version is the ceiling and leaves when a competitor looks better.
+**Apply when.** You shipped a better version/feature but only announced it externally; support pitches the migration only at the cancel moment.
+**The move.** Proactively offer upgrades and migrations to active users — not release emails nobody reads or an Instagram post. Ask: "When we shipped the last relevant feature or version, how many active customers were told?" Offering migration at cancellation converts a clean expansion into emergency retention. Track Net Revenue Retention (NRR); in B2B SaaS, NRR above 110% separates sustainable growth from a leaky funnel.
+**Voice.** "The migration only showed up as a reaction to my complaint, after I started making noise."
+**Source.** [@richardrx · 2026-05-19](https://x.com/richardrx/status/2056715097796411514)
+
+## Design the cancel screen — it's your last conversation, not a form
+**Principle.** The cancellation screen is the most ignored yet one of the most important pages in the product; treating it as a bureaucratic form wastes your final chance to retain.
+**Apply when.** Cancel flow is just "Are you sure?" with two buttons, or Stripe's default template, while signup was crafted with care.
+**The move.** Three plays: (1) Show concrete loss — "You'll lose access to relationship data on your 476 configured clients and 8 months of history"; concrete loss outweighs abstract benefit (loss aversion). (2) Offer an alternative before goodbye — "Pause 30 days instead?" or one more free month (ChatGPT nails this). (3) Collect the reason usefully via an open question — "What was missing for you to stay?" — not a dropdown that rarely lists the real reason.
+**Voice.** "If you invested to bring your user here, invest the last 30 seconds trying to keep them."
+**Source.** [@richardrx · 2026-05-13](https://x.com/richardrx/status/2054562119962501186)
+
+## Churn starts on the landing page, not at cancel
+**Principle.** If the LP promises one thing and the product delivers another, you create an expectation debt that charges interest every day the user thinks "this isn't what I expected" — and the disappointment is pre-programmed even if the product is excellent.
+**Apply when.** 30-day churn is high but NPS is fine — the problem is likely what you promised before they entered, not the product.
+**The move.** Audit three common mismatches: (1) result promise vs. tool delivery ("Increase sales 30%" → a metrics dashboard); (2) simplicity promise vs. complex product ("Set up in 5 minutes" → 47 fields, 3 integrations, 20-min tutorial); (3) promise aimed at the wrong ICP (LP speaks to a 2-person startup; product was built for a 15-person team at scale). Recalibrate the promise to match real delivery and ICP.
+**Voice.** "The user bought a result and got a colorful spreadsheet."
+**Source.** [@richardrx · 2026-04-29](https://x.com/richardrx/status/2049568514311172355)
+
+## Anchor one-time-job products to a recurring life event
+**Principle.** A product hired to solve a one-off problem generates structural churn: a user who loves it and still cancels isn't unhappy — they finished the job they came to do, and there was no continuous value to bring them back.
+**Apply when.** You have 4.2 stars and positive NPS yet rising churn; the product solves a point problem (resume builder, contract/legal-doc generator, data migration tool, pitch-deck builder, due-diligence platform).
+**The move.** Use jobs-to-be-done thinking. Instead of faking engagement, anchor the product to an event that already recurs in the user's life and returns yearly without a push. Ask: "If the job my product does is finished, what life event justifies the user coming back?" If there's no answer, it's a business-model problem, not a product problem.
+**Evidence.** TurboTax (US income-tax software) tied itself to tax season, turning the product into a ritual because the event makes the use inevitable.
+**Source.** [@richardrx · 2026-04-24](https://x.com/richardrx/status/2047620778338795918)
+
+## Treat support volume as a design problem, not a staffing one
+**Principle.** What looks like a support problem is usually a design problem — you cut ticket volume during onboarding itself, with an interface that answers questions before they're asked. Low-ticket digital products generate up to 3x more support than conventional tickets.
+**Apply when.** Support is your biggest bottleneck, especially with low-ticket/impulse-buy products; you're tempted to just automate tickets.
+**The move.** Three drivers of low-ticket support load: different buyer profile (less patience, less digital familiarity, more expectation of human help); impulse purchase (low friction → buys without understanding → seeks support); inverted opportunity cost (asking is easier than searching). For SaaS, redesign the journey: contextual in-product FAQ, self-answering UI. Automating support treats the symptom; redesigning the journey fixes the cause and can cut churn too.
+**Evidence.** An old McAfee case cut support volume by 90% by implementing an FAQ — plain text, no chatbot.
+**Source.** [@richardrx · 2026-04-23](https://x.com/richardrx/status/2047289409238712726)
+
+## Strip the jargon before you blame onboarding
+**Principle.** Churn that looks like a product problem is often a language problem: a technical founder writes product and sales copy in jargon, the ICP buys on a leap of faith, never perceives value, accumulates small disappointments, and cancels — looking like a missing feature on the dashboard.
+**Apply when.** Churn is high and you've already revised onboarding and product — revise language and structure next.
+**The move.** Watch two biases: the curse of knowledge (you know too much and forget the other person doesn't) and the easy-speech bias (simple language reads as more trustworthy and raises awareness). Rewrite dense, jargon-heavy copy into plain language even for complex topics.
+**Visual.** Side-by-side: a dense, legalese contract clause (red X) vs. a plain-language rewrite "In this contract you authorize the bank…" (green check), with an "Easy-speech bias" callout. — `../assets/2041829519611371727__1.jpg`
+**Voice.** "On the dashboard it looks like a missing feature; it was a mismatch between your discourse and their understanding."
+**Source.** [@richardrx · 2026-04-08](https://x.com/richardrx/status/2041829519611371727)
+
+## Engineer addiction like a game so CS isn't a churn tax
+**Principle.** Customer Success is the tax you pay for a non-addictive product — if you need an army of CSMs to stop cancellations, the product failed. Your real competitor isn't another startup; it's boredom, and boredom has infinite CAC. The CNPJ buying your SaaS is the same brain that plays Candy Crush; reward neuroscience is identical. Win retention across three game-design phases.
+**Apply when.** Diagnose by behavior: dropout at minutes 2–8 of onboarding = Phase 1; ~1.3 logins/week when it should be 4x = Phase 2; one departing employee kills the whole account = Phase 3. LTV:CAC below 3:1 means you're funding a product that can't stand organically.
+**The move.** **Phase 1 — Time-to-value vs. cognitive load:** ditch the setup wizard (asking work before delivering value reads as hostile territory in 10 seconds); use progressive disclosure, let users create and see results before asking for email/card. Mechanism: Zeigarnik effect (incomplete-loop tension) + endowment effect (people value 3x more what they helped build). Empty states must sell the dream — never show "0 data" or blank templates; populate a demo simulating day-30 usage. **Phase 2 — Habit loop / retention as biology:** passive software that only reacts is a failure to build dependency; ship proactive variable rewards. The mesolimbic reward system releases dopamine on anticipation, not the reward itself; predictable rewards (monthly report) build tolerance, variable ones ("we detected a positive anomaly yesterday") keep the loop alive. Convert vanity metrics into loss-aversion triggers: "Your team broke a record and you haven't seen it" + temporal data scarcity ("sync in 24h or lose the weekly benchmark"). **Phase 3 — Defensive moat:** single-player products die when the champion leaves — you built dependence on a person, not the org. Build multiplayer mode + data debt via social switching cost + network effects. Make User A's work block/depend on User B; reports needing multi-stakeholder approval; dashboards aggregating 3 departments. When quitting requires an alignment meeting across Sales, Ops and Finance, you reach negative churn by bureaucratic inertia; accumulated datasets add organizational endowment effect.
+**Voice.** "Stop blaming the customer. Your product is boring. And in the attention game, boring is bankruptcy."
+**Source.** [@richardrx · 2026-01-30](https://x.com/richardrx/status/2017274698699067466)

package/skills/frontend/design/revenue-centric-design/references/conversion-and-landing-pages.md

@@ -0,0 +1,132 @@
+# Conversion & Landing Pages
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## "Paint the button" is judging the last line of a long cascade
+**Principle.** The visual layer of a landing page is the tip of a cascade that begins at the ICP — so "make it more colorful" critiques the *end* of a process as if it were the start.
+**Apply when.** Gathering or acting on LP feedback, or reaching for button color first.
+**The move.** Work the cascade in order: ICP → the buyer's **awareness level** (Eugene Schwartz's 5 stages) → what you say and how → visual positioning (tone → form, color, type, space). Low awareness: open on the problem, name the pain in the first fold, then the mechanism and your fix. Higher awareness: go straight to your advantages vs. alternatives. Jump to button color and you've silently (and probably wrongly) answered who you sell to, their awareness, which pain, and what tone.
+**Voice.** "They're looking at the end of a process and thinking it's the beginning."
+**Source.** [@richardrx · 2026-06-23](https://x.com/richardrx/status/2069469303464730988)
+
+## Scaling cold traffic is an honesty test for your page
+**Principle.** Conversion measured on warm audiences (existing followers) is inflated — they forgive the page's flaws. Only cold traffic reveals how much of your rate is the page versus borrowed trust.
+**Apply when.** Ad spend goes up but revenue barely moves, and the conversion rate "drops" even though you fixed nothing.
+**The move.** Treat any baseline built on warm public as fiction, not a performance number. When you scale budget into cold traffic and the rate collapses, that gap is the page's real ceiling — fix the obvious page defects first, then judge media.
+**Evidence.** A founder tripled ad spend; revenue rose only 11%. Warm-traffic conversion of ~3% (driven by Instagram followers) cratered to 0.5% on cold traffic; fixing the obvious lifted it to 2% — 4x the real number.
+**Voice.** "Scaling budget into cold traffic works like an honesty test: it shows how much of your conversion is your page and how much is borrowed trust."
+**Source.** [@richardrx · 2026-06-08](https://x.com/richardrx/status/2063972594223661127)
+
+## Write the CTA microcopy, not the button color
+**Principle.** The CTA label moves conversion far more than button color or shape — it's the last thing the user reads before deciding, so it must reduce the mental effort of simulating what happens next.
+**Apply when.** A technical founder is A/B testing button colors for weeks over a 0.3% (non-significant) delta while the label still says "Sign up" with no click trigger.
+**The move.** Make the CTA answer the three questions the brain asks before clicking: (1) what happens when I click, (2) how long it takes, (3) what it costs/commits. "Sign up" answers none; "Start free in 30s" answers two. Add a click trigger (the small line under the CTA) to answer the rest and break an objection: "Start Free Trial" + "14 days, no card". Rooted in outcome bias and Construal Level Theory (making the outcome concrete).
+**Voice.** "The button is the last thing the user reads before deciding — treat it as such."
+**Source.** [@richardrx · 2026-05-25](https://x.com/richardrx/status/2058875777739866490)
+
+## Cut CAC by filtering on the landing page, not the media
+**Principle.** High CAC is rarely a media problem — it's usually a filtering problem. The landing page can qualify leads before the form, killing deals that were never going to close.
+**Apply when.** Clicks become leads, leads become SDR calls, calls don't close, and founders react by swapping creative or channel (or blaming the SDR).
+**The move.** Pull three filtering levers so the lead self-selects without feeling filtered: (1) copy specificity — "Cash flow for service providers billing R$500k–R$3M" beats "Organize your finances"; (2) visible pricing — screens out no-budget leads so sales only meets real objections; (3) a qualification question as the first interaction (or copy/examples that play that role). CAC is cost per closed deal, not cost per lead.
+**Evidence.** If you close 1 in 50 leads, dropping to 30 leads with 1 close nearly doubles media efficiency — same spend, lower CAC.
+**Voice.** "The lead with no money won't magically generate money between the landing page and the sales call."
+**Source.** [@richardrx · 2026-05-18](https://x.com/richardrx/status/2056385204785213446)
+
+## Aim for 4.2–4.5 stars, not a perfect 5
+**Principle.** A flawless rating reads as fake; consumers distrust unanimity. A profile that includes constructive criticism feels more authentic and converts better than pure praise.
+**Apply when.** Building or curating reviews/ratings and social proof on a landing page or product.
+**The move.** Let imperfection show. Stack the highest-converting combination: a detailed case study with quantifiable ROI, ideally a video testimonial from a brand recognizable to your ICP, plus customer logos. Avoid the common failure — social proof done badly: identical cards, first-name-only, all 5 stars, generic avatars instead of a real photo. Make each review verifiable (e.g., link to the actual LinkedIn post).
+**Evidence.** Northwestern: purchase probability peaks at 4.2–4.5 stars, not 5. Testimonials lift LP conversion up to 34% (VWO); 5+ reviews → 270% more likely to be bought (Yotpo); 93% read reviews before buying (BrightLocal).
+**Visual.** A social-proof wall done right: real faces, names + roles, verifiable reviews, and recognizable client logos (Volkswagen, Coca-Cola, Samsung, Itaú, Volvo, DocuSign, Hotmart) under a "+10,000 professionals" headline — `../assets/2054910531132183030__1.jpg`
+**Voice.** "Credibility drives conversion."
+**Source.** [@richardrx · 2026-05-14](https://x.com/richardrx/status/2054910531132183030)
+
+## Compress the decision window — shorten the path to action below the path to doubt
+**Principle.** The purchase decision is mostly made before checkout. Conversion is architecture: the user converts when the path to the action is shorter than the path to doubt, because every extra second of deliberation raises the odds they close the tab.
+**Apply when.** You're optimizing the checkout, CTA, or headline while ignoring the deliberation time upstream.
+**The move.** Compress decision time two ways: pressurize the environment with real scarcity ("Only 1 room left at this price", "Booked 3 times in the last hour") — driven by loss aversion (Kahneman: losing hurts up to ~2x more than the equivalent gain), so "1 left" registers as "I'll lose this"; or remove steps entirely (Amazon's patented 1-Click ordering).
+**Evidence.** Booking runs 1,000+ simultaneous experiments (per Lukas Vermeer, 8 yrs leading experimentation); showing sold-out hotels alongside available ones *raised* bookings by sharpening perceived scarcity.
+**Voice.** "The user converts when the path to the action is shorter than the path to doubt."
+**Source.** [@richardrx · 2026-05-11](https://x.com/richardrx/status/2053832356293738914)
+
+## Don't clone the page — the converting layer is invisible
+**Principle.** A converting sales page is the visible shell of an invisible system. Copying the layout copies what's cheapest to produce; the expensive part (research) stays invisible and gets left behind.
+**Apply when.** A page "looks like it works" and you're tempted to clone it for your own offer.
+**The move.** Before copying, ask: what on this page is a function of the *product*, and what is a function of the *customer research* done before writing each line and placing each element? The hidden layer is customer vocabulary pulled from interviews, objections ordered to the ICP's specific fear, social proof hand-picked to resonate, and a core promise tuned to the stated desire. This error has a name: cargo cult — replicating the visible ritual hoping to summon the result, without grasping the causal mechanism.
+**Evidence.** Two ~95%-identical pages, same niche/offer/order: 4% vs 0.6%. The 4% page belonged to Richard's client; the 0.6% was a near-pixel clone by a builder — who unknowingly DM'd the original team to complain it wasn't converting.
+**Voice.** "There's a name for copying the form expecting the function. It's called cargo cult."
+**Source.** [@richardrx · 2026-05-09](https://x.com/richardrx/status/2053086365781205142)
+
+## Pass the 5-second test — lead with the problem, not the feature
+**Principle.** A visitor scans your LP for ~5 seconds. If they can't answer what it does, who it's for, and why they should care, they leave — they won't stay to figure it out. Conversion begins on the first line.
+**Apply when.** Your hero opens by describing what the product *is/does* (a feature/category) instead of the visitor's pain.
+**The move.** Open with the visitor's problem, not yourself. "AI-powered project management platform" → meh; "Your team loses 6 hours a week hunting for information" → keep going. One talks about itself, the other talks about me. If the first line doesn't connect with the pain, the rest of the page goes invisible.
+**Voice.** "If you who built it can't answer in 5 seconds, your visitor can't either."
+**Source.** [@richardrx · 2026-05-01](https://x.com/richardrx/status/2050280273682510230)
+
+## Fix contrast, layout, and trust before rewriting copy
+**Principle.** The brain processes three pre-verbal variables — contrast, on-screen placement, and trust — before it reads the words, and they usually move the needle more than any headline.
+**Apply when.** You're rewriting home copy for weeks chasing conversion without touching the visual/attentional layer.
+**The move.** (1) Contrast is relative to surroundings, not an isolated color — a big, differently-shaped button in whitespace is *seen before it's read* (accessibility ratio 4.5:1 is a floor, not the goal). (2) Placement: Fitts's law (closer, bigger targets get clicked more) plus the F-pattern (Nielsen Norman eyetracking) — a CTA bottom-right with no visual anchor sits outside the attentional map. (3) Trust is built in four reinforcing layers: a real (non-stock) human face, a known brand or specific verifiable proof, an offer that fits the stated problem, and a solution mechanism logically coherent with the promise. When all four align, the user converts without knowing why; when one fails, they invent a rational reason to leave.
+**Voice.** "Optimizing copy without working contrast, placement, and trust is masking the symptom."
+**Source.** [@richardrx · 2026-04-28](https://x.com/richardrx/status/2049215050997784774)
+
+## Specificity is the difference between decoration and persuasion
+**Principle.** Generic LP copy gets discarded by the brain; specific messages are processed faster and generate more trust. A converting LP shows the *transformation* the product causes, not just what it does.
+**Apply when.** Your hero reads "The complete platform for [generic category]", a 5-feature subtitle, "Start free", and no real social proof — the default Brazilian SaaS template.
+**The move.** Fix the four standard failures: (1) "Complete platform" means nothing → "Cut new-dev onboarding time 40%"; (2) features on top → lead with the pain, feature as the solution (nobody wakes up wanting a "custom report feature"); (3) "Start free" is the weakest CTA (no value, no risk reduction, no urgency) → "See your first report in 2 minutes"; (4) "Used by Company X" proves nothing → "We cut Company X's churn from 12% to 6%". One page describes, the other sells.
+**Evidence.** Across 30 Brazilian SaaS LPs: descriptive vs transformation-led ran 0.5% vs 3% conversion — same traffic, 6x more leads — driven by argument sequence and promise specificity, not visual design.
+**Source.** [@richardrx · 2026-04-17](https://x.com/richardrx/status/2045154631974539650)
+
+## Users scan, they don't read — give the primary action obvious contrast
+**Principle.** Users scan interfaces, weighing cognitive effort against payoff, and ignore most of it. They enter with one question — "What can I do here?" — so the primary action must win on contrast within seconds.
+**Apply when.** The main CTA competes with 6 other elements, or the most important action is buried inside a dropdown that requires a click to reveal.
+**The move.** Make the primary action visually dominant so it's found in a glance. If the key button competes with too many elements it loses prominence; if it's hidden behind interaction it's effectively invisible. Leverage image superiority to guide attention down the page.
+**Visual.** A login screen annotated with two biases — "limited choice bias" (a single dominant Google sign-in button) and "image superiority" (a vivid hero illustration pulling the eye) — `../assets/2042013751742705816__1.jpg`
+**Source.** [@richardrx · 2026-04-08](https://x.com/richardrx/status/2042013751742705816)
+
+## Judge a landing page by conversion, not by beauty
+**Principle.** A landing page isn't a beauty contest — it has one measurable job: qualify the user and lower CAC by turning traffic into revenue. Evaluating a static image with no context is nearly useless.
+**Apply when.** The timeline turns into "AI vs human" / "who designed it better" debates that ignore conversion, while obvious conversion flaws go unaddressed.
+**The move.** Treat conversion as a continuous loop, never an isolated event: form a thesis → ship the interface and collect data → find where the user hesitated, form a new hypothesis, and optimize the next cycle. The debate defaults to aesthetics because it's easier to opine on looks than to measure results — which is exactly what keeps most LPs underperforming.
+**Visual.** A side-by-side "Google Stitch vs Human" LP comparison being judged on looks alone — context for the argument, not a model to copy — `../assets/2034638793219694734__q__1.jpg`
+**Voice.** "Product design doesn't compete with art. It sells."
+**Source.** [@richardrx · 2026-03-19](https://x.com/richardrx/status/2034638793219694734)
+
+## Converting pages are often ugly — design for performance, not applause
+**Principle.** There's an invisible war between branding (looking good in the screenshot) and performance (conversion, retention, expansion). The page that puts money in the till is often visually aggressive, text-heavy, and far from the Apple aesthetic founders dream of.
+**Apply when.** You're choosing between a page that wins design compliments and one built to convert.
+**The move.** Engineer the converting pattern even if the artist in you cringes: (1) one obvious attention point — eyes go where they must; (2) a high-contrast CTA with redundancy; (3) a clear promise delivering easily-perceived value; (4) guarantee, social proof, and a free element to reduce risk aversion; (5) organic images by the second fold to back the offer and build trust.
+**Evidence.** The analyzed page (quoted): 100 visits → 19 signups, a 19% conversion rate.
+**Visual.** An "ugly-but-converts" waterproofing LP: urgency bar, high-contrast orange CTAs, a short above-the-fold form, stat row (12,500+ / 4.9★ / lifetime warranty), and trust badges — `../assets/2023777916673220817__q__1.jpg`
+**Voice.** "Some LPs go after compliments, others go after conversion."
+**Source.** [@richardrx · 2026-02-17](https://x.com/richardrx/status/2023777916673220817)
+
+## Design the features page for skimming, not reading
+**Principle.** Almost nobody reads your features page — they skim three bullets and hunt for a demo video. Design for that behavior (with the caveat that the more conscious, technical slice of your ICP *will* read the detail).
+**Apply when.** You're packing a features page with dense prose expecting visitors to read it top to bottom.
+**The move.** Front-load three crisp bullets and make a demo video easy to find; let the deep copy serve the minority of technical, high-awareness buyers who actually read it.
+**Source.** [@richardrx · 2026-02-09](https://x.com/richardrx/status/2020815036168437814)
+
+## No clicks out, plus brutal CTA contrast
+**Principle.** For conversion you want little distraction and lots of redundancy. Any clickable element that leads off-page is lost conversion — no matter how prestigious the source.
+**Apply when.** You're tempted to link out to a glowing NY Times piece or a top influencer's video, or your CTA blends into the interface.
+**The move.** Kill outbound clicks entirely. Make the CTA generate strong contrast against the rest of the interface in position, size, and color — if it isn't easy to notice and click, it won't be clicked.
+**Visual.** A wireframe showing the level of contrast a CTA button needs against the surrounding interface — `../assets/2019514730696565238__1.jpg`
+**Source.** [@richardrx · 2026-02-05](https://x.com/richardrx/status/2019514730696565238)
+
+## Debug ICP and awareness level before touching design
+**Principle.** Conversion is context engineering — who arrives, with what pain, at what stage, needing what proof. Two invisible variables must be debugged before writing a line of code: the Who (ICP) and the When (awareness level). Visual design comes last.
+**Apply when.** Your LP underperforms and you reach for button-color tweaks; or you define ICP by demographics.
+**The move.** (1) Reject the demographic fallacy: geography/age/income is a bad proxy — King Charles and Ozzy Osbourne are demographic twins with opposite needs. Real ICP is *buying criteria* (trigger, pain, prior attempt, proof needed); persona is just biography, the spec for your user. (2) Map the visitor's Eugene Schwartz awareness level. Rule: headline speaks to the current stage; proof pushes them one stage forward. Selling "Solution" to the "Unaware" is proposing on a first date. Debug order: ICP wrong → awareness wrong → proof insufficient for the stage → only then touch visual design.
+
+Awareness → angle / hero / proof:
+- **Unaware** — symptom & identity / "Still doing X this way?" / simple diagnostic, checklist, benchmark
+- **Problem-aware** — cost & urgency / "If you have X, you're losing Y" / numbers, before/after, calculation
+- **Solution-aware** — trade-offs & selection / "3 ways to solve X — why the 3rd scales" / honest comparison, matrix
+- **Product-aware** — differentiation & proof stack / "Why us, why now" / cases, demo, objections
+- **Most aware** — final risk & friction / "Swap X for Y in Z days, no risk" / guarantees, onboarding, effort reduction
+
+**Visual.** Schwartz's 5 awareness stages as a rising ramp (Unaware → Problem → Solution → Product → Most Aware) — `../assets/2011427153133351046__3.jpg`; plus the demographic-twins diagram (Charles vs Ozzy, identical on paper) — `../assets/2011427153133351046__2.jpg`
+**Voice.** "There's no 'conversion rate' in a vacuum. There's contextualized conversion."
+**Source.** [@richardrx · 2026-01-14](https://x.com/richardrx/status/2011427153133351046)

package/skills/frontend/design/revenue-centric-design/references/metrics-and-experimentation.md

@@ -0,0 +1,31 @@
+# Metrics, Experimentation & Business Math
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## Don't mistake signups for traction
+**Principle.** Signups are the cheapest action a user takes, so they measure curiosity, not value — especially in freemium. Real growth is whether people come back and do the action that delivers value.
+**Apply when.** A rising signup curve on the dashboard feels like proof of traction, particularly under a freemium model.
+**The move.** Treat signups as top-of-funnel only — never stop reading there. Track who returns on day 2 and day 7 (D1/D7 retention) and how many complete the value-delivering action (activation). Paid media can inflate signups while real retention stays flat.
+**Voice.** "The signup curve climbs with paid traffic, but usage and activation only climb with a good product."
+**Source.** [@richardrx · 2026-06-11](https://x.com/richardrx/status/2065082771987394651)
+
+## Don't bet your product on an underpowered A/B test
+**Principle.** Most A/B tests in small SaaS lack the volume to prove anything, yet founders swap the whole product on the result. Testing without enough sample to conclude is the trap.
+**Apply when.** You're in traction or survival stage, ran a test for a week, saw "variant B won by 12%," and want to ship it everywhere.
+**The move.** Before running, compute the minimum sample size (free calculators exist); if you can't hit that floor in reasonable time, don't start. Test big things (headline, offer, pricing structure, onboarding) since large effects need less sample. Never stop a test because the number looked pretty mid-way. With no volume, decide by qualitative research — five good interviews beat an underpowered A/B test. Beware the law of small numbers and confirmation bias.
+**Evidence.** ProfitWell is categorical: don't A/B test price — you'll never have the volume or context for it to mean anything.
+**Source.** [@richardrx · 2026-06-01](https://x.com/richardrx/status/2061463480868229189)
+
+## Celebrate signal quality, not list size
+**Principle.** A waitlist exists to validate that a pain is one people pay to solve — not to sell. Absolute size is a vanity metric; conversion-weighted quality is the real signal.
+**Apply when.** You launch a waitlist and feel tempted to celebrate raw headcount.
+**The move.** Convert size to expected customers before reacting: a good waitlist converts 15–20% to paying, above 30% is excellent. 53 people at 20% = 10 customers; 1,000 people at 1% = 10 customers — same result, different perception. Until there's a transaction, there's no validated hypothesis.
+**Voice.** "Founders celebrate the size of the list when they should celebrate the quality of the signal."
+**Source.** [@richardrx · 2026-04-17](https://x.com/richardrx/status/2045094511106220220)
+
+## Translate churn points into LTV, not percentages
+**Principle.** Most people watch churn %, but few compute what each point costs in accumulated LTV over 12 months. Cutting churn is a cash lever that needs no price hike or new acquisition.
+**Apply when.** You're staring at a churn percentage and treating it as a vanity number rather than money.
+**The move.** Do the churn→LTV math: at 25% monthly churn on 1,000 users you must add 250 new users/month just to break even — kill paid traffic and the product dies in ~4 months. Then improve retention without Figma: define the Aha Moment, measure time-to-value (TTV) from signup to it, ask "how do I deliver this faster?", break it into micro-wins if you can't, then test, measure, repeat.
+**Evidence.** Finance SaaS, ARPU R$120: cutting churn 5 points (25%→20%) is +R$72,000/year in cash, with no price change and no extra acquisition.
+**Source.** [@richardrx · 2026-04-06](https://x.com/richardrx/status/2041184077106004289)