@ranimontagna/agent-toolkit 0.1.19 → 0.1.20

package/README.md

@@ -210,6 +210,10 @@ skills/
         debugging.md
         testing.md
     design/
+      revenue-centric-design/
+        SKILL.md
+        assets/
+        references/
       ui-ux-pro-max/
         SKILL.md
         data/
@@ -356,6 +360,7 @@ Follow these steps...
 | `devops` | `docker-patterns` | Adapted from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/docker-patterns) and [`sickn33/antigravity-awesome-skills`](https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/docker-expert), both under the MIT license |
 | `frontend` | `accessibility` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/accessibility) under the MIT license |
 | `frontend` | `astro-developer` | Copied from the official [`withastro/astro`](https://github.com/withastro/astro/tree/main/.agents/skills/astro-developer) repository under the MIT license |
+| `frontend` | `revenue-centric-design` | Copied from Helio Costa's [`revenue-centric-design`](https://github.com/heliocosta-dev/revenue-centric-design) under source-available custom terms requiring attribution and excluding gambling/betting/casino use |
 | `frontend` | `ui-ux-pro-max` | Copied from Next Level Builder's [`ui-ux-pro-max-skill`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/tree/main/.claude/skills/ui-ux-pro-max) under the MIT license |
 | `frontend` | `gsap-core` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-core) under the MIT license |
 | `frontend` | `gsap-frameworks` | Copied from GreenSock's [`gsap-skills`](https://github.com/greensock/gsap-skills/tree/main/skills/gsap-frameworks) under the MIT license |
@@ -661,8 +666,8 @@ Release a new npm version by updating `package.json`, pushing the change to
 `main`, then pushing a matching tag:
 
 ```bash
-git tag v0.1.19
-git push origin v0.1.19
+git tag v0.1.20
+git push origin v0.1.20
 ```
 
 For normal releases, prefer the scripted flow. It bumps `package.json`, updates

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranimontagna/agent-toolkit",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Personal AI agent toolkit installer for Claude Code, Codex CLI, OpenCode, Gemini CLI, Antigravity and graph-aware workflows.",
   "type": "module",
   "packageManager": "pnpm@11.8.0",

package/skills/frontend/design/revenue-centric-design/LICENSE

@@ -0,0 +1,30 @@
+Revenue-Centric Design Skill — License & Usage Terms
+Copyright (c) 2026 the curators of this repository.
+
+The underlying ideas, frameworks, examples, and the coined term "Revenue-Centric
+Design" are the intellectual property of Richard (@richardrx on X) and are used
+here WITH PERMISSION. This repository is a distilled, translated index of his
+public posts, shared for educational and reference use.
+
+You are granted permission to use, copy, and share this material, subject to ALL
+of the following conditions:
+
+1. ATTRIBUTION. You must retain clear attribution to Richard (@richardrx) and a
+   link to the source. Do not misrepresent the origin of these ideas.
+
+2. NO GAMBLING / BETTING / CASINO USE. You may NOT use this material — in whole
+   or in part — to design, build, optimize, market, or grow betting, casino,
+   gambling, or other real-money games-of-chance products or projects (including
+   loot-box and real-money-gaming mechanics). This restriction was set by the
+   original author as an explicit condition of reuse and MUST be preserved in any
+   copy or derivative.
+
+3. PRESERVE THESE TERMS. Any copy or derivative work must include this license in
+   full, including the restrictions above.
+
+4. NO WARRANTY. This material is provided "AS IS", without warranty of any kind,
+   express or implied. The curators and the original author are not liable for any
+   claim, damages, or other liability arising from its use.
+
+Note: Because of the field-of-use restriction in clause 2, this is a
+SOURCE-AVAILABLE license, not an OSI-approved open-source license.

package/skills/frontend/design/revenue-centric-design/NOTICE.md

@@ -0,0 +1,12 @@
+# Third-party notice
+
+This skill was copied from Helio Costa's Revenue-Centric Design repository.
+
+- Source: https://github.com/heliocosta-dev/revenue-centric-design
+- Source commit: 6fa20cb4f91fa97bce9197be3f78b168784eb772
+- License: Source-available custom terms; attribution required, no gambling/betting/casino use
+- Copyright: Copyright (c) 2026 the curators of the source repository
+
+The upstream `updater/` maintenance tooling was intentionally not vendored.
+The runtime skill files, references, and referenced assets are included. The
+upstream license is included in `LICENSE`.

package/skills/frontend/design/revenue-centric-design/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: revenue-centric-design
+description: "Playbook for SaaS and startup product design that improves conversion, activation, retention, pricing, positioning, GTM, monetization, and AI-era differentiation. Use for product UX, landing pages, onboarding, trials, churn, pricing, growth, or positioning. Not for gambling, betting, or casino products."
+---
+
+# Revenue-Centric Design
+
+A distilled playbook of **101 principles** from **Richard ([@richardrx](https://x.com/richardrx), "Design for startups")** —
+a product designer specializing in conversion-rate optimization, churn reduction, and applied
+behavioral science (ex-Volkswagen, PayPal, IBM). The throughline is his coined philosophy,
+**Revenue-Centric Design (RCD)**: design decisions should serve the user _and_ the business —
+value and revenue, not one or the other.
+
+Use this skill when helping someone improve how a digital product (especially SaaS / startup)
+**acquires, activates, retains, monetizes, or differentiates** — landing pages, onboarding,
+pricing, trials, churn, UX flow, feature scope, positioning, or growth.
+
+## Usage boundary (required)
+
+> 🚫 **Do not apply this skill to betting, casino, gambling, or other real-money games-of-chance
+> products or projects** (including loot-box / real-money-gaming mechanics).
+
+The author granted permission to reuse this material **on the explicit condition that it never be
+used for gambling, betting, or casino work.** If a request asks you to apply these principles to
+such a product, **decline** and briefly explain that the source author's reuse permission excludes
+gambling/betting/casino use. This is a hard constraint set by the author, not a stylistic choice.
+
+## How to use it
+
+1. Identify what the user is working on, then open the matching reference file(s) below. Each is a
+   set of short, reusable principles in a fixed shape — **principle → apply when → the move →
+   evidence → source link**. Load only what's relevant (progressive disclosure).
+2. Ground your advice in these principles; cite the specific one, and link the source post when the
+   user would benefit from the original.
+3. Lead with the **named mechanism** (e.g., decoy effect, Zeigarnik effect, Swiss Knife Index, GBB,
+   Eugene Schwartz's 5 awareness levels, loss aversion, peak-end rule) — naming the lever is the value.
+4. Stay evidence-led: many principles carry a study, stat, or case. Keep the citation attached
+   rather than hand-waving.
+
+## The spine: Revenue-Centric Design in 9 principles
+
+1. **Neutrality is omission** — an interface that doesn't direct hurts conversion.
+2. **Who talks to everyone convinces no one** — no ICP → generic value → worse retention.
+3. **Value first, ask later** — proof must arrive before the user questions their choice.
+4. **Your promise is the size of your proof** — the market believes what you demonstrate, not what you claim.
+5. **Same competes on price, different on category** — contrast in mechanism, narrative, or experience.
+6. **Default is the decision you made for the user** — the initial state defines mass behavior.
+7. **Retention is built, not requested** — perceived loss retains more than promised benefit.
+8. **Expansion is born of usage** — upgrade at the moment of the limit, never by interruption.
+9. **Price is a filter** — pricing defines who enters, who stays, and who expands.
+
+## Reference library
+
+| When the question is about…                                                   | Open                                                                         |
+| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Landing pages, hero/copy, CTAs, social proof, awareness levels, CRO           | [conversion-and-landing-pages](references/conversion-and-landing-pages.md)   |
+| First-run, empty states, aha moment, TTV, activation, trial-as-onboarding     | [onboarding-and-activation](references/onboarding-and-activation.md)         |
+| Cancellation, retention, expectation debt, NRR, jobs-to-be-done, support load | [churn-and-retention](references/churn-and-retention.md)                     |
+| Pricing tables, decoy/anchoring, GBB, trial-with-card, upgrade paths          | [pricing-and-monetization](references/pricing-and-monetization.md)           |
+| Cognitive biases & persuasion tactics (cross-cutting toolkit)                 | [behavioral-science-toolkit](references/behavioral-science-toolkit.md)       |
+| Feature scope, Swiss Knife Index, feature adoption, attention hierarchy       | [product-strategy-and-features](references/product-strategy-and-features.md) |
+| Design philosophy, the RCD principles, design process & method                | [revenue-centric-design](references/revenue-centric-design.md)               |
+| ICP, niche, founder-fit, distribution, PLG, Bullseye, first customers         | [positioning-icp-and-gtm](references/positioning-icp-and-gtm.md)             |
+| Differentiating in the AI era, moats, commoditization                         | [ai-era-differentiation](references/ai-era-differentiation.md)               |
+| A/B testing rigor, vanity metrics, churn→LTV math, signal quality             | [metrics-and-experimentation](references/metrics-and-experimentation.md)     |
+
+Informational diagrams and screenshots referenced by the principles live in `assets/`.
+
+## Provenance
+
+101 curated posts by [@richardrx](https://x.com/richardrx), extracted with a valid X API key and
+distilled **with the author's permission**, translated from Portuguese to English. Every principle
+links back to its source post. Reuse is subject to the gambling/betting/casino exclusion above.

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)