@ranimontagna/agent-toolkit 0.1.19 → 0.1.20

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)

package/skills/frontend/design/revenue-centric-design/references/onboarding-and-activation.md

@@ -0,0 +1,148 @@
+# Onboarding & Activation
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## An onboarding video welcomes — it doesn't teach
+**Principle.** A good onboarding video isn't a manual (nobody reads their car's or iPhone's). It welcomes, builds connection, shows the product at a glance, and points to where value comes fastest.
+**Apply when.** Designing first-run onboarding or a welcome video.
+**The move.** Aim it at cutting TTV, support tickets, and the lost feeling — not at educating. Length follows your ICP's urgency (someone rushing vs. someone happy to build Lego). No actor or fancy set — Richard recorded his in Screen Studio and it beat many big products'.
+**Visual.** A "Your account was created!" welcome modal with an embedded intro-video thumbnail and a single "Next" CTA — `../assets/2067987722954735812__1.jpg`
+**Voice.** "Your product doesn't need a manual either — have you read your car's?"
+**Source.** [@richardrx · 2026-06-19](https://x.com/richardrx/status/2067987722954735812)
+
+## Rising MRR with rising churn means you lost them on day one
+**Principle.** When MRR and churn climb together, the user didn't leave in month 2 — they were lost the first day, dropped into a dead empty-state dashboard with nothing guiding them to value.
+**Apply when.** Churn is creeping up and you're tempted to blame the product or add features.
+**The move.** It isn't a feature gap — measure **TTV** (time-to-value) and get obsessed with shrinking it. CAC, LTV and activation are *product* metrics, not marketing; with weak retention, acquiring more just fills a leaky bucket faster.
+**Voice.** "It took two months to cancel, but you lost him the first day after signup."
+**Source.** [@richardrx · 2026-06-18](https://x.com/richardrx/status/2067591574138052804)
+
+## Measure activation, not signups
+**Principle.** Technical founders track the wrong onboarding metrics; signups, session time, and tour completion all flatter you without proving the user reached value.
+**Apply when.** You're judging onboarding by signups, time-in-product, or "completed the tour."
+**The move.** Swap each vanity metric for its real counterpart: signups → activation rate, session time → time-to-first-useful-action (and its repetition), onboarding completion → D7 retention. Find your aha moment empirically: look at what every paying customer did in week one that churned users didn't (often a collaborative act — invite, share, comment). Anchor on TTV/time-to-value.
+**Evidence.** Userpilot benchmark (547 companies): avg TTV 1d 12h 23m; top performers under 5 min. SaaS activation rate avg 30–37%, top quartile 40%+, under 20% = structural problem. D7 retention avg 10–15%, over 30% is strong.
+**Voice.** "If you can't say how long your user takes from signup to aha moment, you're not measuring what matters."
+**Source.** [@richardrx · 2026-05-27](https://x.com/richardrx/status/2059616501544468624)
+
+## Put friction in the right place, not zero friction everywhere
+**Principle.** Friction in the wrong place kills the product; friction in the right place qualifies and retains. "Less friction" is not a universal law.
+**Apply when.** You're reflexively cutting clicks and fields, or your human sales team is doing qualification the product should do.
+**The move.** Remove friction at trial signup (it kills acquisition), but add calibrated friction in three spots: (1) trial with card upfront filters commercial intent; (2) mandatory onboarding before the dashboard turns users into power-users faster; (3) a 6–8 field enterprise demo form (role, team size, current tool, budget, timeline) lowers lead volume but raises close rate. The mechanism is effort justification (Aronson & Mills, 1959) — same root as the endowment and IKEA effects.
+**Evidence.** ChartMogul 2026: opt-in trial (no card) converts 8.9%; opt-out (with card) converts 31.4%. Superhuman requires a 30-min human call before access.
+**Voice.** "How much qualification effort is your human seller doing that the product should do before they even step in?"
+**Source.** [@richardrx · 2026-05-21](https://x.com/richardrx/status/2057436163841941980)
+
+## Never ship a blank dashboard
+**Principle.** The empty dashboard arrives at the user's peak of curiosity and answers it with a void — this is where most SaaS loses the trial. Every second spent deciding what to do is a second closer to quitting.
+**Apply when.** A new user lands post-signup on a screen with no data and no direction.
+**The move.** Four fixes: (1) empty state with a next-action hint — the CTA points straight to value; (2) seed sample data so they see the destination before starting; (3) one single clear action ("Import your first spreadsheet"), not eight, not a 12-step tour; (4) visible progress from the first click — start the bar at 20%, not 0%, so completion feels already underway.
+**Voice.** "A blank dashboard looks neutral, even tidy — but it just makes the user stop and think about what to do."
+**Source.** [@richardrx · 2026-05-12](https://x.com/richardrx/status/2054283657934758021)
+
+## Design onboarding as a behavioral trigger, not a feature tour
+**Principle.** Silent non-activation — users who sign up, vanish in five minutes, and never formally churn — is an activation problem, not a product one. Onboarding should fire a behavior, not narrate features.
+**Apply when.** New users evaporate without complaint and you never learn their name.
+**The move.** Find the single behavior that statistically separates retained from lost users, make it your activation north star, and measure every onboarding decision against it. Shift focus from explaining features to forcing that behavior fast. Exploit the Zeigarnik effect: open small loops (complete profile, invite 3 colleagues, send first message) so the user carries an unfinished task.
+**Evidence.** Slack: teams exchanging 2,000 messages had 93% probability of staying. Facebook's equivalent: 7 friends in 10 days — the company's single focus, repeated at every all-hands.
+**Voice.** "What's the number that separates who stays from who evaporates — and how does the user hit it in under 24h?"
+**Source.** [@richardrx · 2026-05-11](https://x.com/richardrx/status/2053878928494690414)
+
+## Map the journey from session replays, not from your diagram
+**Principle.** The founder's 12-step journey is built top-down (what the product wants); the user runs 4 steps bottom-up (the specific problem they opened the tab to solve). The gap between them is where avoidable early-stage churn lives — and it's invisible because the founder only ever lived the creator's journey.
+**Apply when.** You "know" the happy path but can't state what % of users actually execute it.
+**The move.** Three steps, no Figma: (1) write your version of the user journey in numbered steps, on paper; (2) open five real session recordings from the first 7 days and note what each user actually does, in order, with timing — including what they try and abandon; (3) lay both lists side by side. The report is in the differences; each divergence is a hypothesis to confirm or kill.
+**Voice.** "The user journey is what shows up in the replay; what's in Figma and Excalidraw is a hypothesis."
+**Source.** [@richardrx · 2026-05-08](https://x.com/richardrx/status/2052711138572263474)
+
+## Add declarative friction, cut administrative friction
+**Principle.** "Good onboarding is short onboarding" is incomplete. There are two frictions: administrative (collects data the system uses later, buys the user nothing) and declarative (forces the user to state what they came to do — costs a beat, buys commitment, customization, and journey direction).
+**Apply when.** Auditing onboarding steps; deciding what to cut versus expand.
+**The move.** Test each step: is it collecting data or making the user declare intent? Collecting only → candidate to cut. Declaring intent → candidate to expand. A declaration ("what do you sell, what's your long-term goal?") creates a micro-commitment to the outcome before the user touches the product, and lets the journey branch (recommendations, tutorials, next actions) off that answer.
+**Evidence.** Brazilian payments platform cut time-from-signup-to-first-sale from 24.2 to 2.5 days by adding a ~30-second intent step (positioned between signup and product), not by removing steps.
+**Voice.** "Onboarding is also the first chance the user has to declare to themselves what they came to do."
+**Source.** [@richardrx · 2026-05-07](https://x.com/richardrx/status/2052350703541039324)
+
+## Trial conversion is a journey problem, not a pricing problem
+**Principle.** A trial is a test of value; if the user never proves value to themselves, no price or trial length saves it. Conversion fails for three diagnosable reasons.
+**Apply when.** Users sign up, do "a bunch of nothing," and never return.
+**The move.** Diagnose which failure mode applies: (1) blank dashboard → make the first step obvious and immediate, drive to value or a micro-win, drop "explore our product"; (2) lost before value → install Clarity, watch where they stall, optimize that click; (3) lost to life → send a progress email ("you created 3 reports, your team accessed 12 times, you're in the top 20%"), not a generic "trial ending."
+**Voice.** "The longest trial in the world doesn't save bad onboarding."
+**Source.** [@richardrx · 2026-05-06](https://x.com/richardrx/status/2052096365128273956)
+
+## Make onboarding active, not passive
+**Principle.** Passive onboarding (tooltips, guided tour, docs — learn if you want) assumes the user will explore. They won't: they have 47 tabs open, WhatsApp pinging, and will do the bare minimum before deciding whether to return. Active onboarding designs a sequence where each action delivers value and that value triggers the next.
+**Apply when.** Your onboarding opens with "Welcome, here's the documentation."
+**The move.** Assume you know the shortest path to value better than the user does. Design that path, strip the friction, and make sure they arrive. Don't ask "what's the minimum the user must do?" — ask "what's the smallest action that delivers the most value in the least time?"
+**Evidence.** Slack drops you into a channel and makes you send a message first — you use the product before any tutorial.
+**Voice.** "Understanding by doing beats understanding by reading."
+**Source.** [@richardrx · 2026-04-22](https://x.com/richardrx/status/2046959126245249288)
+
+## Treat sub-30-day churn as an onboarding fix, not a feature gap
+**Principle.** Most early-stage SaaS churn happens in the first 30 days — which means it's onboarding, not product. Adding features only makes it worse by adding complexity.
+**Apply when.** Users leave before they ever liked what you built, and you're tempted to ship more features.
+**The move.** Diagnose with three questions: (1) how long to the first real result? If "it depends" or over a day, you're bleeding users; (2) does the user know where they are? Use a progress bar/checklist — Progress effect: someone seeing 30% done is likelier to finish than someone at 0%, so starting at 0% is a design error; (3) what happens when they drop mid-flow — email, push, nothing? Use the Zeigarnik effect to remind them they started.
+**Voice.** "Sub-30-day churn rarely dies to features; it dies to the right sequence of micro-interactions that deliver value before asking for effort."
+**Source.** [@richardrx · 2026-04-20](https://x.com/richardrx/status/2046212675017887881)
+
+## Deliver the promised result before teaching mechanics
+**Principle.** Nobody wants to learn to use your product; they want the result you promised in the landing-page hero. Teaching mechanics first ("create a project → add a member → configure integrations") is boring; delivering value first converts.
+**Apply when.** Your onboarding is a checklist of setup mechanics rather than a path to the outcome.
+**The move.** Lead with the outcome ("In 2 minutes you'll see your first report → let's start with the data you already have → done, that's the insight competitors pay consultants for"). Reframe progress with the Progress effect by crediting effort already spent ("You've done the hard part, just 3 steps left"). Keep loops small (Zeigarnik effect — people close loops only if they look closable). Pre-select the right plan from data you collected instead of asking, then offer the upsell.
+**Voice.** "The gap between 5% and 15% trial conversion is in these details — not features, not price — in the sequence of micro-decisions you designed without realizing you were designing."
+**Source.** [@richardrx · 2026-04-16](https://x.com/richardrx/status/2044785090832543998)
+
+## Qualify by behavior, not by a long signup form
+**Principle.** Friction at the wrong moment kills conversion, and qualification by behavior is more precise than qualification by form. The "more qualified leads" argument for long forms usually loses.
+**Apply when.** You're weighing an 8-field signup form against email + password.
+**The move.** Default to the minimal form and let qualification happen later, inside the product, from real behavior. Deciding where to add versus remove friction is what separates a product that grows from one that spins its wheels — but it's contextual ("it depends").
+**Evidence.** Same product, two founders: 8-field form (name, email, company, role, phone, segment, team size, how-did-you-hear) → 12% signup rate; email + password only → 34%.
+**Visual.** Annotated onboarding step (DevNoodles): an ICP/intent question flagged "Zeigarnik effect" (the step progress dots) and a B2C/B2B card selector flagged "Progress effect" — showing where each bias is engineered into the flow. — `../assets/2042558822825239030__1.jpg`
+**Source.** [@richardrx · 2026-04-10](https://x.com/richardrx/status/2042558822825239030)
+
+## Celebrate the activation moment, don't just confirm it
+**Principle.** At the emotional peak of activation, a number is data but a rising graph is progress — and progress triggers dopamine and an emotional memory tied to the product. Most SaaS confirms where it should celebrate.
+**Apply when.** A user completes a hard-won first action (first transaction, first integration) and you respond with a static success state.
+**The move.** Engineer the peak moment precisely at the point of highest emotional vulnerability in activation — right after the user clears the effort. Show motion and accomplishment proportional to the effort invested. This is the peak-end rule: users judge an experience by its emotional peak and its ending, rarely by the average.
+**Evidence.** Stripe shows a rising graph (not a number) the moment the first transaction processes — the founder who integrated it at 3am remembers exactly where they were.
+**Voice.** "A number would have done the job. The graph created a customer."
+**Source.** [@richardrx · 2026-04-04](https://x.com/richardrx/status/2040415841628651689)
+
+## Cut time-to-value by reorder and removal, not feature changes
+**Principle.** High TTV is almost never product complexity — it's the form and order in which things happen. Each day between signup and first result is another day of abandonment risk; abandonment = churn.
+**Apply when.** Your activation flow is slow and you assume the product itself is the bottleneck.
+**The move.** Three iteration cycles, no product changes: (1) reduce cognitive load by grouping and standardizing what the user must fill in; (2) work with legal/compliance to strip everything required by habit but not by actual necessity; (3) invert the sequence so the user feels value before facing the heaviest step.
+**Evidence.** Major Brazilian payments platform: 24 days → 2.5 days to first sale (89.7% reduction), no product changes, no cutting of mandatory compliance steps.
+**Visual.** Month-by-month TTV table: Jan 24.2d → Feb 19.6d → Mar 16.8d → Apr 9.3d → May 2.5d, alongside accounts created / approved / new sellers per month. — `../assets/2037583944283996418__1.jpg`
+**Source.** [@richardrx · 2026-03-27](https://x.com/richardrx/status/2037583944283996418)
+
+## Give the trial an active goal, not passive access
+**Principle.** A passive trial ("use it if you want, cancel guilt-free") builds no commitment; a trial with an active goal builds commitment before billing. Each completed day raises the psychological cost of canceling — the user starts defending a decision they already made, before paying.
+**Apply when.** Your trial is open-ended access with no challenge or target.
+**The move.** Set a recurring daily goal during the trial that the user opts into and completes. The named mechanism is progressive commitment. The product can be good or bad — done right, the onboarding itself is excellent.
+**Evidence.** Wispr Flow challenges trial users to dictate 100+ words a day for 7 days — looks generous, is behavioral science.
+**Source.** [@richardrx · 2026-03-26](https://x.com/richardrx/status/2037316988981174464)
+
+## Calibrate the first step to the user's real willingness
+**Principle.** Users don't rationally evaluate the first task — they evaluate perceived effort. Ask too much up front and the cognitive cost of even imagining the task is paralyzing, and they quit before starting. This is the activation-barrier effect.
+**Apply when.** Your first onboarding step bundles setup, data import, team invites, and project creation — or demands a campaign-sized action.
+**The move.** Two biases fix it: (1) started-progress effect — show what the user has already done before what's left; a loyalty card with the first stamp pre-filled beats a blank 9-stamp card, because the starting point changes perceived distance to the finish; (2) small-steps effect — "Create one story today" has radically lower perceived cost than "post 5×/week," even when the underlying task is identical. Sequence effort so the user hits first value before noticing how much they invested; build momentum.
+**Evidence.** Instagram A/B test made "Create 5 new public reels" the first task — for someone who barely posts weekly, that's paralyzing.
+**Visual.** Bad first-step example: a weekly-progress checklist at "0% completed" whose top item is "Create 5 new public reels (0/5)." — `../assets/2036461688505909250__1.jpg`
+**Voice.** "Asking for more isn't necessarily the problem; asking for all of it at once, with no progress anchor and no commitment ladder, is."
+**Source.** [@richardrx · 2026-03-24](https://x.com/richardrx/status/2036461688505909250)
+
+## Treat onboarding as the bridge between CAC and LTV
+**Principle.** Founders obsess over CAC and landing-page conversion but are blind to activation cost. Onboarding isn't an interface tutorial — it's the bridge from CAC to LTV and the point of maximum leverage to expand revenue. Cancellation happens on day one; it's merely formalized when Stripe's billing reminder lands.
+**Apply when.** Users enter the trial without intent to a result and ghost before ever paying.
+**The move.** Two fixes: (1) turn support into UX — every onboarding support ticket is a design failure; map recurring setup questions and convert the answers into features or in-flow tooltips; (2) compress TTV obsessively — make the user experience the product's core promise in the least time possible. If they must configure 5 screens before any result, you've already lost.
+**Voice.** "Letting a user into the trial without intent of a result isn't self-service. Design's job doesn't end at signup — that's where it starts paying you back."
+**Source.** [@richardrx · 2026-03-13](https://x.com/richardrx/status/2032485654811083005)
+
+## Pick onboarding patterns by awareness × flow complexity
+**Principle.** There's no best onboarding in the abstract — only the one that removes friction and delivers value early for your users. Treat the nine patterns as behavior-shaping mechanisms, not UI components, and select by two axes.
+**Apply when.** Choosing or combining onboarding patterns for a new flow (SaaS, PLG, B2B early stage).
+**The move.** The nine patterns (pattern → ideal use / tradeoff): **1. Welcome modal** → high-awareness ICP or low-complexity products; easy to build, easy to ignore. **2. Wizard / product tour** → B2B and complex/high-cost-of-error flows (fintech, compliance); long tours cause boredom and need constant upkeep. **3. Contextual tooltips** → advanced/secondary features; slashes support tickets but users may miss them if contrast is poor. **4. Empty state** (his favorite) → dashboards, lists, data-dependent areas; if executed well it's mandatory, directs the first action and accelerates TTV. **5. Personalization** → products serving many ICPs with different journeys; great CRM data, but too long kills signup conversion. **6. Checklists** → critical flows with mandatory prerequisites (webhook, KYC); exploits the Zeigarnik effect, but a long list breeds aversion — every item must move toward value, no bureaucratic tasks. **7. Goal-setting** → habit products (finance, productivity, health); uses commitment bias, but a broken goal can break the emotional contract. **8. Sample data** → sell the dream of a full, organized product before the user inputs anything (distinct from skeleton screens). **9. Use cases / demos** → products burning expensive resources (AI tokens) with infinite outputs; show max potential without forcing creativity from scratch.
+Selection rule — two axes: **awareness level** (low = needs guidance; high = needs speed) × **flow complexity** (high = needs structure). Four cases: low-awareness + high-complexity → tours + checklists + personalization; low + low → modal + empty state; high + high → checklist + tooltip + empty state; high + low → modal + empty state (then get out of the user's way). Build vs. buy is financial/operational, not aesthetic — buy (Wistia, PostHog, Sprig) when speed is critical, dev is overloaded, or you're running A/B tests; build when onboarding is strategic, you need perfect aesthetic integration, or you must avoid third-party dependence.
+**Voice.** "Onboarding's job isn't to teach the user — nobody likes an instruction manual — it's to remove cognitive effort and deliver utility as fast as possible. TTV correlates directly with churn."
+**Source.** [@richardrx · 2026-02-04](https://x.com/richardrx/status/2019019293761941566)

package/skills/frontend/design/revenue-centric-design/references/positioning-icp-and-gtm.md

@@ -0,0 +1,64 @@
+# Positioning, ICP & Go-to-Market
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## Size the market with TAM → SAM → SOM (and know which one matters)
+**Principle.** Your real market is far smaller than the population — TAM is a theoretical ceiling (Brazil's 213M becomes ~101M credit-card holders for a paid app). Investors often ignore a TAM under ~R$1B, but the number that matters is the **SOM** — what you can actually capture.
+**Apply when.** Sizing a market, writing a deck, or judging whether a niche is big enough.
+**The move.** TAM = total addressable ceiling; **SAM** = the realistic slice your model reaches (~40% in his example); **SOM** = the 1–5% you truly win in ~36 months — and SOM isn't a guessed %, it comes from real CAC, activation, support capacity and LTV. You can't change your TAM; you change how much of your SAM you convert and retain.
+**Evidence.** RepareCar: ~76k mechanic shops (honest TAM) → SAM ~47k → ~3% ≈ 1,414 shops ≈ R$1.6M ARR; current pace (~10 shops/day) ≈ 7% of SAM in 12 months.
+**Visual.** TAM/SAM/SOM concentric-circle diagram with definitions — `../assets/2070140923380420796__1.jpg`
+**Source.** [@richardrx · 2026-06-25](https://x.com/richardrx/status/2070140923380420796)
+
+## Frame the referral prize as a gift to the friend, not a commission to the referrer
+**Principle.** Member-get-member (MGM) referral programs win on framing and timing, not just on a two-sided reward. Money makes the exchange feel transactional; an in-product benefit feels like a genuine gift.
+**Apply when.** Designing or fixing a referral program and defaulting to "refer a friend, get $20."
+**The move.** Apply the framing effect: surface the prize on the receiver's side ("João gave you 500MB"). Ask for the referral at the peak of value (right after a concrete win, or when the user hits a limit). Avoid cash; give a reward that deepens use of your own product. Embed it as continuous in-product operation, not a one-off campaign. Caveat: referral amplifies a product people already love; it can't fix one nobody recommends for free.
+**Evidence.** Dropbox grew 3900% in 15 months (100k → 4M users), peaking near 3M invites in a single month; ~1/3 of users already arrived via word-of-mouth before the program.
+**Voice.** "A referral amplifies a product people already love — it doesn't fix a product nobody recommends for free."
+**Source.** [@richardrx · 2026-06-02](https://x.com/richardrx/status/2061766945582559509)
+
+## Pick a deliberately under-served niche as your ICP
+**Principle.** A clear ICP (ideal customer profile) is not "everyone who could use my product." It's a deliberately chosen, under-served niche — and a sharp niche beats no niche, because you can't out-fight the entrenched generalist giant.
+**Apply when.** Early traction; tempted to "embrace the world" out of fear of a small TAM.
+**The move.** Validate four ICP filters: (1) feels the pain with real weight — pain is proportional to what's lost when unsolved (a lost lead costs a face-aesthetics clinic R$3,000 vs. R$60 for a barber); (2) big enough TAM to sustain operations; (3) money to pay your required ticket so unit economics close; (4) founder-fit, giving native language, a fast validation network, and instinct that money can't buy. With a clear ICP, failure has a diagnosis ("I got the messaging wrong"); without one, you can't tell if product, copy, channel, price, or audience failed — and every test burns runway.
+**Voice.** "A generalist ERP is hard to sell; an ERP for cabinetmaking is a different conversation."
+**Source.** [@richardrx · 2026-05-19](https://x.com/richardrx/status/2056789797646029232)
+
+## Don't claim PLG without the four structural conditions
+**Principle.** Product-led growth (PLG) is a consequence of structural conditions, not a product decision you declare. Most B2B SaaS that pitches PLG is really sales-led wearing a PLG label.
+**Apply when.** Writing a pitch deck or strategy and calling the motion "self-service" / PLG.
+**The move.** Require all four conditions: (1) TTV < 10 minutes — if it needs a consultant demo, API support, or paid implementation, it's not PLG (tell: full trial, zero activation); (2) ticket below ~R$1,000 — higher means a buying committee; (3) native virality or collaboration (Notion, Figma, Slack pull users in; a CRM/AI tool needs SDRs, demos, follow-up); (4) a huge addressable market with a real bottom-up TAM. If you fail these, run sales-led honestly.
+**Evidence.** Brazil has ~20,000 companies with 100+ employees, and only ~a dozen B2B SaaS where PLG makes real economic sense.
+**Voice.** "Founders love PLG because it seems to delete the part they don't master — selling."
+**Source.** [@richardrx · 2026-05-04](https://x.com/richardrx/status/2051262752547536941)
+
+## Charge your first ten users from day one
+**Principle.** The first ten users define the product's entire curve, and payment is the cheapest test of real pain — curiosity is free, an open wallet demands a concrete problem.
+**Apply when.** Validating a new product and tempted to give early access away to "build a base."
+**The move.** Source the first ten from closed communities, personal reach, or pure guerrilla. Charge even while in prototype. When someone says they can't pay, ask directly: "What does the system need to do for you to pay right now?" Treat the payment friction as part of the test. Collect dense feedback; only start visual design after ~20 paying users. For B2C apps the method shifts (e.g., pre-sale of a solution-in-progress) but the principle holds.
+**Evidence.** RepareCar's first 25 auto shops tested the product in prototype; the team visited each and charged at the end, designing visuals only after 20 paying shops.
+**Voice.** "Curiosity is free; an open wallet demands a concrete problem."
+**Source.** [@richardrx · 2026-04-26](https://x.com/richardrx/status/2048359526487716333)
+
+## Reverse-engineer the funnel math before celebrating an MRR target
+**Principle.** Building the product is the easy part; distribution is the game. A revenue target is really a traffic-and-retention problem, and churn quietly resets the whole funnel every month.
+**Apply when.** Someone asks "is it hard to hit X MRR?" or you're sizing acquisition for a target customer count.
+**The move.** Work backwards: to net 2,500 customers at 5% LP conversion you need 50,000 visitors; from ads at 3% creative CTR, ~1.6M impressions (5% and 3% are top-decile — most land at 1–2% LP and under 1% CTR, so you test dozens). Then add the leaky bucket: at 20% monthly churn, average customer life is 5 months, so you replace 500 customers every month forever just to stand still (≈10,000 visitors / 333,000 impressions). The problem lives at the intersection of dev, design, and marketing — none alone owns it.
+**Evidence.** 20% monthly churn → 5-month average lifetime; at low ticket many operate at 40–50% churn, so "the bucket never fills."
+**Voice.** "Building the product is the easy part; distribution is the game."
+**Source.** [@richardrx · 2026-04-20](https://x.com/richardrx/status/2046222319912132977)
+
+## Concentrate channels with the Bullseye framework, not scattershot testing
+**Principle.** Testing ten channels at once means you never know what drove results and you blame the channel when the business stalls. Distribution needs prioritized focus — and a perfect channel still fails if the receiving structure leaks.
+**Apply when.** You're spreading content and traffic across many channels with no clear read on what works.
+**The move.** Use the Bullseye framework (from the book *Traction*): three rings of priority. Inner ring = at most three highest-potential channels with total focus; middle ring = up to six channels you probe with small experiments; outer ring = everything plausible long-term, no active focus now. Choose between channels with an ICE Score (Impact, Confidence, Ease, each 0–10, divide by 3, prioritize). Crucial gap the book skips: scaling distribution onto a broken reception structure (LP, onboarding, first product steps) yields no growth — distribution and retention are simultaneous, not sequential.
+**Visual.** Bullseye as nested circles — What's Possible → What's Probable → What's Working — beside a "Marketing Framework for Startups" triangle (Prioritization, Testing, Quick Iteration). — `../assets/2036035304868434115__1.jpg`
+**Source.** [@richardrx · 2026-03-23](https://x.com/richardrx/status/2036035304868434115)
+
+## Diagnose the bottleneck: no entries is distribution, leaving without paying is design
+**Principle.** Design can't save a "ghost product." Design optimizes and raises the LTV of something that already has traffic; it can't manufacture demand.
+**Apply when.** A builder ships an app, gets near-zero users, and hopes a redesign will rescue it.
+**The move.** Split the diagnosis cleanly: if nobody enters your product, it's a distribution problem; if they enter, don't pay, and leave, it's design. Read *Traction* even if you can afford an agency or a marketing team — the lever isn't just cost-per-channel but each channel's awareness level, which drives different conversion and retention behavior depending on where and how the user arrived.
+**Voice.** "If nobody enters your product, it's distribution. If they enter, don't pay, and leave, that's design."
+**Source.** [@richardrx · 2026-02-28](https://x.com/richardrx/status/2027721170569564521)

package/skills/frontend/design/revenue-centric-design/references/pricing-and-monetization.md

@@ -0,0 +1,87 @@
+# Pricing & Monetization Psychology
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## The freemium trap, in numbers: higher conversion, far lower cash
+**Principle.** A free plan lifts signup conversion but can crush the economics — the higher top-of-funnel number hides a worse business.
+**Apply when.** You're tempted by freemium's better conversion rate.
+**The move.** Run the funnel (same R$80k/mo traffic, plans from R$199). **With freemium:** ~8% → 800 signups → 80% activate → 5% pay = 32 payers (R$6,368 MRR), saturating ~160 payers under 20% churn, while 768 free users burn AI tokens (~$0.08 each) — real CAC ≈ R$2,540/payer, payback ~13 months. **Without:** ~3% → 300 payers = R$59,700 MRR (~10×), CAC ~R$275, payback ~6 weeks, LTV:CAC 5:1 that reinvests its own profit. Freemium only pays off if free brings *organic/viral* users you didn't pay for.
+**Voice.** "One scenario reinvests its own profit; the other funds losses until the money runs out."
+**Source.** [@richardrx · 2026-07-01](https://x.com/richardrx/status/2072312844784152628)
+
+## Whether freemium works is decided by the cost to serve a free user
+**Principle.** Freemium isn't good or bad in the abstract — the *cost of free* decides, and it hinges on (1) how much it costs to serve non-payers and (2) how long/expensive activation is.
+**Apply when.** Considering a free plan, especially as a bootstrapped (non-bigtech) founder.
+**The move.** If serving a free user costs almost nothing and TTV is short, free becomes an acquisition channel (Slack — first message in minutes; it's the short TTV, not the cash, that sustains it). If the product runs on AI (dollar-priced tokens) or activation is long, a free account is an expensive bet that a small fraction funds — which needs deep pockets (the exception, not the average founder). On a friendly average, only ~3–4% of freemium converts. Otherwise: charge — well, and early.
+**Voice.** "For an AI product, your free user was never free."
+**Source.** [@richardrx · 2026-06-30](https://x.com/richardrx/status/2071962778072469560)
+
+## Price is the cheapest money — stop anchoring it to the cheapest competitor
+**Principle.** Pricing is a SaaS's biggest lever, yet ~90% of products are underpriced — the founder, who knows every limitation, anchors on the cheapest competitor instead of on value delivered. The buyer only sees the problem solved.
+**Apply when.** Setting or revisiting price; fearing a "no."
+**The move.** Raise toward value. A 30% price increase doesn't yield 30% MRR (some churn), but what remains is nearly pure cash — no acquisition in between — while growing a channel 30% costs money, time, and has a ceiling. Low price costs you later: less budget to reach your ICP, a CAC-obsession trap (the real metric is the CAC↔LTV *gap*, which price widens on both sides), and higher churn (cheap attracts uncommitted buyers). Design link: the number must be sustained by perceived value — your page and first use justify or destroy it.
+**Voice.** "Charging more without seeming to be worth more is just raising the price of rejection."
+**Source.** [@richardrx · 2026-06-29](https://x.com/richardrx/status/2071634185228329219)
+
+## Make the middle plan the one you actually want to sell
+**Principle.** Each plan has a behavioral job, not just a price; the plan you most want to sell should sit in the middle, flanked by a decoy below and an anchor above.
+**Apply when.** Building or auditing a SaaS pricing page, especially if you copied competitors without assigning each tier a role.
+**The move.** Use the decoy effect: place your target (e.g. Pro) in the middle; make the tier below it clearly inferior on one important attribute (user cap, no critical integration, no priority support) so Pro looks obvious. Keep exactly three plans — four+ triggers the paradox of choice and users stall. Add a top tier (Enterprise) purely to anchor price perception. Ask: "What is my decoy today?" If you can't name one, it likely doesn't exist.
+**Evidence.** Ariely's MIT test of The Economist's tiers: with the print-only decoy, 16%/84% chose online/combo; removing it flipped choices to 68%/32%, cutting combo revenue by more than half. Estimated +30–43% subscription revenue.
+**Visual.** Economist subscription page; the decoy's removal shifts combo-plan share from 84% down to 32% — `../assets/2059951433827426437__1.jpg`
+**Voice.** "Option B was never built to be sold — it was built to make C look obvious. It's the bait."
+**Source.** [@richardrx · 2026-05-28](https://x.com/richardrx/status/2059951433827426437)
+
+## Ask for the card in trial — but optimize for the right ICP, not raw conversion
+**Principle.** Requiring a credit card multiplies trial-to-paid conversion but shrinks signups; the goal is the model that attracts and retains the right ICP, not the one with the highest headline conversion.
+**Apply when.** Choosing trial-with-card vs trial-without-card (or freemium), or designing recurring billing for a Brazilian market.
+**The move.** Weigh the funnel both ways. Trial-with-card converts harder but starves you of volume; trial-without-card floods the funnel with low-intent users. Run the full math, not just the conversion rate. In Brazil, also account for PIX recorrente, whose dynamics differ from monthly card billing.
+**Evidence.** ChartMogul 2026 (US, 200 products): trial-with-card converts ~31.4% vs 8.9% without — 3x+. Worked funnel: 1,000 visitors → 30 trials → 9.4 paying (with card) vs 85 trials → 7.5 paying (without). Author observes PIX-recorrente cohorts churn more than card cohorts.
+**Voice.** "Don't ask which model converts more — ask which model attracts and retains the right ICP."
+**Source.** [@richardrx · 2026-05-15](https://x.com/richardrx/status/2055247161349054950)
+
+## Frame the upgrade as a loss at the moment of value, not a feature you're selling
+**Principle.** Low upgrade rates are usually a framing-and-timing problem, not a price problem; remind users what they've already invested and what they stand to lose.
+**Apply when.** A happy, active free user never upgrades, or your upgrade rate sits below 5%.
+**The move.** Three framings beat generic limit/discount/feature-gate prompts. (1) Sunk cost: surface the assets they've built — "You created 47 custom reports. On the free plan you lose access to 40." (2) Loss aversion: framing loss outconverts framing gain — "You'll lose access to 8 months of history" beats "Get unlimited history." (3) Limited-access gate timed to an imminent, known result — "Your report is ready. To export as PDF, activate Pro." The timing/context of the gate matters more than the gate itself.
+**Voice.** "If your upgrade rate is below 5%, the problem probably isn't price — it's how and when you're asking."
+**Source.** [@richardrx · 2026-04-21](https://x.com/richardrx/status/2046544442216054981)
+
+## Engineer the comparison frame with a decoy and a high anchor — and drop Free from the top
+**Principle.** Conversion shifts when you change the frame of comparison, not the product; equal-looking options cause delay, and showing Free first anchors everyone to zero so everything else feels expensive.
+**Apply when.** You run the default Free / Pro / Enterprise (sob consulta) ladder and Pro isn't converting.
+**The move.** Insert a decoy: a Starter just below Pro with irritating limitations (e.g. R$79 vs Pro R$99) so users compare Starter↔Pro and Pro wins for R$20 more. Remove Free from the visible top so the first number isn't zero — anchoring means the first price seen sets the reference; lead with a higher/previous/Enterprise price so Pro at R$99 reads as cheap.
+**Evidence.** The Economist sold 3x more print+digital after adding a same-price print-only decoy nobody bought. Author cites documented tests lifting conversion 10–20% via reframing alone.
+**Voice.** "You're competing against your own free plan. And losing."
+**Source.** [@richardrx · 2026-04-14](https://x.com/richardrx/status/2044014136770580743)
+
+## Tie the trial's end to value consumed, not the calendar
+**Principle.** Blocking access on a fixed day count (7/14/28) is a lazy rule; the billing trigger should fire on value consumption, after the user's first real win.
+**Apply when.** You copied a competitor's 14-day trial and paid conversion is failing, or you're setting trial length from scratch.
+**The move.** Never paywall before a clear micro-win or solving the core problem — doing so kills conversion and breeds bad word of mouth. Set length using four variables: (1) Product complexity — enterprise needs time for compliance/security review, not just the user. (2) Time to Value — Spotify delivers in seconds, a CRM needs days of data. (3) Usage frequency — rarely-used products may need long trials, or none at all (a once-a-year tax tool shouldn't have a trial). (4) Card entry — no card means a shorter trial to create urgency; with card, watch silent next-month churn. Note: sunk cost only bites if the user built a real asset — a bad onboarding produces frustration, not switching cost.
+**Voice.** "Locking access purely on the calendar is a lazy rule that can cost you dearly — you're burning CAC without knowing where value lands."
+**Source.** [@richardrx · 2026-03-16](https://x.com/richardrx/status/2033502548301091057)
+
+## Order pricing rows by the serial-position effect: killer feature first, differentiator last
+**Principle.** Users don't read pricing lists linearly; attention and memory cluster on the first and last items, so feature order is itself a conversion lever.
+**Apply when.** Laying out the feature rows inside a pricing card or comparison table.
+**The move.** Exploit the serial-position effect (primacy + recency). Top: value anchor — never "24/7 support"; lead with the core/killer feature that solves the ICP's main pain and justifies ~80% of the ticket and the ROI. Middle: utilitarian features (exports, integrations, storage limits) the user won't memorize but will scan to compare against the next plan. Bottom (nearest the CTA): the differentiator, bonus, or loss-aversion hook — a lifetime guarantee or dedicated support. The middle of the list is "a cognitive black hole."
+**Visual.** Pricing card emphasizing the bold first row (core feature) and bold last row (super bonus), with greyed utilitarian middle rows — `../assets/2029623167900061970__1.jpg`
+**Voice.** "Pricing success depends not just on what you deliver, but on the order the brain is led to process the value."
+**Source.** [@richardrx · 2026-03-05](https://x.com/richardrx/status/2029623167900061970)
+
+## Build a single value axis, then tune the decoy's distance to your target plan
+**Principle.** A plan ladder must read as one clear progression of value; mixing quantitative and qualitative axes muddles it, and where you place the decoy's price decides which plan looks like the deal.
+**Apply when.** Naming and pricing tiers, or the "value staircase" between your plans isn't obvious to users.
+**The move.** Pick one progression — quantitative (rising credits/users) or qualitative (24/7 human support, special features) — rather than blending both. Borrow Starbucks-style naming (Tall/Grande/Venti) so every tier sounds good and lifts the brand. Then position the decoy: place it near the most expensive plan and the expensive plan looks cheap; place it near the cheapest and the decoy itself becomes the most attractive option.
+**Visual.** Decorative 3D price-tag illustration — no data.
+**Source.** [@richardrx · 2026-02-02](https://x.com/richardrx/status/2018357024543715480)
+
+## Engineer the pricing page with Good-Better-Best and control the comparison
+**Principle.** Lost LTV is rarely about price — it's analysis paralysis from a missing choice architecture. The brain is lazy and judges by relative comparison (priming + anchoring), so if you don't design the anchor, users compare you to "nothing" or to the cheapest competitor.
+**Apply when.** Designing or fixing a pricing page; conversions die at the final step despite strong CAC spend.
+**The move.** Use a Good-Better-Best (GBB) structure: **Good** = a stripped entry plan that anchors a low price but is limited enough to make users feel pain and look up (never make it free — then everything above looks expensive). **Better** = your standard plan, the target for ~80% of buyers; price it closer to Good than to Best so users think "paying only ~20% more I get double?" **Best** = the value anchor that exists mainly to make Better look cheap (bicycle analogy: without the carbon-fiber Best, the carbon-wheel Better looks expensive). Golden rule: keep comparisons on one axis — don't pit "10,000 tokens" against "Priority Support"; prefer linear, ideally asymmetric, growth. Cap at 2–5 plans (6 = anxiety, paradox of choice). Then control which attributes you compare — your own "Brazil vs Paraguay" table — choosing indicators that favor your value thesis. Highlight Better with color/size/badges. "Stop making the user do the math — do the math for them."
+**Evidence.** Cites Briesch et al. (1997) and Mazumdar et al. (2005) on reference-price models, and Chernev (2015) on choice overload.
+**Visual.** Two mirrored BR-vs-PY indicator tables prove framing: swapping which metrics are shown flips which country "wins" — `../assets/2018693884449009956__1.jpg`, `../assets/2018693884449009956__2.jpg`. Four-tier mockup highlights a "Most Popular" target beside a high anchor (Hick's law / few options) — `../assets/2018693884449009956__4.jpg`
+**Voice.** "Your pricing page is killing your LTV — and I can prove it."
+**Source.** [@richardrx · 2026-02-03](https://x.com/richardrx/status/2018693884449009956)

package/skills/frontend/design/revenue-centric-design/references/product-strategy-and-features.md

@@ -0,0 +1,58 @@
+# Product Strategy & Feature Discipline
+
+> Curated, distilled wisdom from @richardrx ("Richard — Design for startups"), translated from Portuguese. Each entry is a reusable principle linked to its source post.
+
+## Run every feature through a two-layer "Swiss Knife filter" before building
+**Principle.** A feature you ship stays forever and charges rent forever, so the right question isn't "is this good?" but "does it deserve the permanent cost it imposes on the product?"
+**Apply when.** A roadmap item feels appealing but nobody applied a filter before committing to build.
+**The move.** Layer 1 — does it deserve to exist? Pass all four: (1) cognitive load (more surface = more to learn + Hick's law decision time); (2) ICP specificity (a CRM for facial-aesthetics clinics charges 5x a generic one); (3) operational cost (maintain/support/document, not build); (4) reinforces the core claim. Layer 2 — build now? Two axes: easily rejectable (clear "no"?) and easily implementable (cost to the validating version, not the dream version). Build the no-brainers first; fail any of the four, kill it guilt-free. To rank survivors, score (New Users + New Revenue + Impact Level) / Effort.
+**Visual.** Prioritization scoring table: (New Users + New Revenue + Impact Level) / Effort = Score — `../assets/2059236567533650119__1.jpg`
+**Voice.** "Every feature that gets in, stays. And it charges rent forever."
+**Source.** [@richardrx · 2026-05-26](https://x.com/richardrx/status/2059236567533650119)
+
+## Feature adoption is a design problem, not a communication problem
+**Principle.** Shipping a feature doesn't make it discovered; users move through their habitual path and never see what they aren't looking for.
+**Apply when.** Three weeks post-launch only ~9% of active users opened the feature and ~4% used it twice, despite changelog, email, and "new" badges.
+**The move.** Stop treating adoption as announcement. The killers are inattentional blindness (users don't see what they aren't seeking) plus status-quo bias (re-learning cost outweighs perceived benefit even when the new way is better). Instead: directional empty states that surface the feature where it'd be used; triggered onboarding fired by the behavior that signals need (CRM user hits the sales page → introduce the objection-busting AI); and a feature adoption rate metric measuring habit/appropriate frequency, not clicks. Anything below an adoption threshold goes back into review.
+**Voice.** "Launching a feature is easy; getting it used is a whole other thing."
+**Source.** [@richardrx · 2026-05-20](https://x.com/richardrx/status/2057162392048476345)
+
+## Compute your Swiss Knife Index to expose feature creep
+**Principle.** A product's worth is measured by features actually used, not features shipped; a bloated product is expensive to sustain and hard to sell, not rich.
+**Apply when.** The roadmap has become a user wishlist and every new feature feels like progress (especially with AI making building cheap).
+**The move.** Swiss Knife Index (SKI) = (features used by >40% of active users in a 30-day window) ÷ (total features). Below 0.3, you own a clumsy Swiss army knife. Fix it with: quarterly audits on real usage data (not team opinion); hide, don't delete (push rarely-used features into advanced settings — reachable for the 3%, gone for the 97%); and a gate on every new feature — "which existing feature do I kill to make cognitive room?" Litmus test: which feature would you show first with 30 seconds to sell? The rest stays invisible until needed. See the academic grounding (2034248739557159293) and the curve (2033880553607364684).
+**Visual.** SKI curve — perceived utility rises then declines past the optimal point as complexity keeps climbing — `../assets/2057124008445796659__1.jpg`
+**Voice.** "Which feature would I show first if I had 30 seconds to sell the product?"
+**Source.** [@richardrx · 2026-05-20](https://x.com/richardrx/status/2057124008445796659)
+
+## Design the attention hierarchy to direct behavior, not just organize info
+**Principle.** A product that organizes delivers access; a product that directs delivers activation — and the visual hierarchy decides which the user gets.
+**Apply when.** "My interface looks good, but people don't use the main features" — and the key feature is buried behind three clicks the user will never make.
+**The move.** Recognize that attention hierarchy is the structure deciding what users see first, find with effort, or never discover. Built without intent, the product sabotages itself: users use what's most salient, which is rarely what retains. Plan the hierarchy to influence behavior — make the value-driving, retention-driving feature the most prominent thing — instead of merely arranging information neatly.
+**Visual.** A typographic demo (huge headline "YOU WILL READ THIS FIRST") proving the eye follows visual weight, not reading order — `../assets/2039399756452057159__1.jpg`
+**Voice.** "A well-designed attention hierarchy makes the user use what retains; a bad one makes them use what's most salient."
+**Source.** [@richardrx · 2026-04-01](https://x.com/richardrx/status/2039399756452057159)
+
+## Ground feature discipline in the academic feature-fatigue research
+**Principle.** Past a cognitive-load threshold, the subjective evaluation of a product doesn't stay neutral — it declines into frustration, confusion, and task abandonment, directly hitting CAC and LTV.
+**Apply when.** You need the evidence behind cutting features, and want to separate pre-purchase appeal from post-purchase utility.
+**The move.** Apply the SKI as a decision criterion grounded in feature fatigue. More features help pre-purchase comparison via distinction bias but hurt the decision via analysis paralysis (more options = longer decisions and more no-decisions; no decision, no conversion). Each extra feature steepens the learning curve — measurable B2B productivity loss — and when value comes slowly, users silently churn before the trial ends, blaming themselves, not the product. This complements the index (2057124008445796659) and the curve (2033880553607364684).
+**Evidence.** Thompson, Hamilton & Rust (2005), "Feature Fatigue," JMR 42(4); distinction bias (Hsee & Zhang 2004); analysis paralysis (Iyengar & Lepper 2000).
+**Voice.** "A product that grows without criteria doesn't get rich — it gets expensive to sustain and hard to sell."
+**Source.** [@richardrx · 2026-03-18](https://x.com/richardrx/status/2034248739557159293)
+
+## Past the optimal feature count, a technically bigger product becomes functionally worse
+**Principle.** The relationship between feature count and perceived utility is non-linear: there's an optimal point, after which each added feature reduces perceived utility while raising sustaining cost and the learning curve.
+**Apply when.** You hear "my interface looks good, but people don't use the main features" — a sign you've passed the optimal point.
+**The move.** Read the SKI curve: utility climbs to a peak (~10 features in the example) then falls as complexity keeps rising. The fix isn't more visibility — it's reducing the product's cognitive load so the rest becomes visible again. Criterion: any feature used by under 10% of the active base must justify its existence or leave. There's no universal ideal count — only the ideal for your ICP, context, and device.
+**Visual.** SKI graph: green perceived-utility curve peaks at the optimal point (10.3 features, 97), red complexity curve rises monotonically and overtakes utility in the "decline zone" — `../assets/2033880553607364684__1.jpg`
+**Voice.** "A bloated product isn't a rich product — it's a product actively destroying the conversion and retention you paid dearly to win."
+**Source.** [@richardrx · 2026-03-17](https://x.com/richardrx/status/2033880553607364684)
+
+## Focus on your core; trying to be "all-in-one" dilutes your value proposition
+**Principle.** Chasing a bigger TAM by going generic destroys retention of your heavy users without converting new ones — the same roadmap mistake in cars and in software.
+**Apply when.** The product is tempted to "embrace the world" and become a do-everything tool, abandoning the specific ICP that made it loved.
+**The move.** Remember who your ICP actually is and build for them, even at the expense of broad appeal. In software, when UI/UX tries to cover everything, the value proposition dilutes: you wreck heavy-user retention and fail to convert newcomers because you've gone generic. Focus relentlessly on the core.
+**Evidence.** Porsche chased China's TAM with generic EVs, abandoning its ICP (visceral flat-six machines); ~€3.9B in losses to reverse the roadmap — operating profit fell from €4,000M (2022) to €40M (9M 2025), margin 18% → 0.2%. [Porsche figures from the quoted post; treat as illustrative.]
+**Voice.** "Focus on your damn core."
+**Source.** [@richardrx · 2026-03-11](https://x.com/richardrx/status/2031722047080960265)