✦ Lodestar

lodestar (n.) — the star that guides a ship's course; a principle that shows the way.

Evidence-graded behavioral design for AI agents. Lodestar is a Claude Code / Claude-compatible agent skill that turns "make it sticky" into named, citable, ethically-bounded design decisions — for mobile apps, web apps, landing pages, and funnels.

---

The problem it solves

When an AI agent designs a product screen, it usually does one of two things: copies the surface of whatever app it was reminded of, or sprinkles in pop-psychology ("dopamine!", "FOMO!") with no evidence and no limits. Both fail the same way — the output can't be defended, measured, or trusted.

Lodestar forces a different path. Every recommendation must:

1. Name the tactic from a ~70-entry library of documented behavioral mechanisms
2. Declare its evidence grade — Strong (replicated science), Moderate (studies/industry data), or Folklore (practitioner heuristics, labeled as such)
3. Translate to concrete UI — components, layout, microcopy, motion — not abstractions
4. Anchor performance claims to real benchmarks — verified industry data, never invented numbers
5. Pass a motivation-science check — Self-Determination Theory before extraction loops
6. Pass a dark-pattern gate — a binding refusal taxonomy built from FTC, Brignull, and academic ontologies

What's inside

lodestar/
├── SKILL.md                          # Router: workflow, stage diagnosis, output format, hard rules
├── references/
│   ├── tactic-library.md             # ~70 tactics: mechanism, lifecycle stage, evidence grade
│   ├── ui-translation.md             # Tactic → component/layout/microcopy/motion specs
│   ├── benchmarks.md                 # Activation, retention, subscription & checkout benchmarks
│   ├── web-cro.md                    # Landing page, form, checkout, pricing-page patterns
│   ├── motivation-science.md         # SDT (scientific backbone), Octalysis, Fogg, Hook
│   ├── dark-patterns.md              # Refusal taxonomy + fair-pattern alternatives
│   └── sources.md                    # Primary sources + re-verification policy
├── docs/
│   ├── USAGE.md                      # Invocation patterns, worked examples, output format
│   ├── METHODOLOGY.md                # How this was researched, validated, and what was excluded
│   ├── ETHICS.md                     # The refusal policy and why it's non-negotiable
│   └── CHANGELOG.md                  # Version history
├── LICENSE
└── README.md                         # You are here

Installation

Claude Code (personal, all projects):

git clone https://github.com/makesupply/lodestar-skill.git ~/.claude/skills/lodestar

Claude Code (single project):

git clone https://github.com/makesupply/lodestar-skill.git .claude/skills/lodestar

Claude.ai / Cowork: upload the folder as a skill, or paste SKILL.md + references/ into a Project's knowledge.

Updating: the install is a git checkout — git -C ~/.claude/skills/lodestar pull.

Quick start

The skill triggers automatically on design work involving onboarding, activation, retention, engagement, gamification, paywalls, pricing, landing pages, or checkout. Or invoke it explicitly:

/lodestar redesign the onboarding for my meditation app — users drop off before their first session

/lodestar review this pricing page and tell me what's working, what's folklore, and what's a dark pattern

/lodestar my D7 retention is 12% — diagnose and propose fixes with benchmarks

Every recommendation arrives as a tactic card:

TACTIC: Endowed progress
MECHANISM: Goal-gradient effect — artificial head-start increases completion [Evidence: Moderate]
STAGE: Onboarding — targets activation rate
UI SPEC: Progress bar starts at 20% after signup ("Account created ✓"); 3 remaining steps visible
ADAPT: Label the pre-completed step with something the user actually did
PAIRS WITH: Completeness meter, reduction
GUARDRAIL: Head-start must reference real completed actions — a fully fictional head-start erodes trust

Design stance

• Diagnosis before design. Name the lifecycle bottleneck (with its benchmark) before touching UI.
• SDT-first. Autonomy, competence, and relatedness are the durable engines of retention; extraction loops (streak punishment, exit-less feeds, fake urgency) are either gated or refused.
• Honest numbers. Benchmarks are dated, sourced medians — not targets, not causal promises. The skill will say "folklore" out loud when that's what the evidence is.
• Truth-gated persuasion. Scarcity, urgency, and social proof are permitted only when literally true.

Provenance

Built from open frameworks and primary sources only — Laws of UX, Persuasive Patterns, Coglode, EAST (UK Behavioural Insights Team), Self-Determination Theory, the Fogg Behavior Model, the Hook Model, FTC/Brignull/Gray dark-pattern taxonomies, and industry benchmark reports (RevenueCat, Amplitude, a16z, Lenny's Newsletter, Baymard, NN/g, CXL). All load-bearing claims were verified against primary sources on 2026-08-04; see docs/METHODOLOGY.md. No proprietary paid content is reproduced.

License

MIT — see LICENSE. Referenced third-party frameworks and reports remain the property of their respective owners; sources are cited in references/sources.md.