diff --git a/.agents/skills/37signals-way/SKILL.md b/.agents/skills/37signals-way/SKILL.md new file mode 100644 index 00000000..7a848045 --- /dev/null +++ b/.agents/skills/37signals-way/SKILL.md @@ -0,0 +1,189 @@ +--- +name: 37signals-way +description: 'Build lean, opinionated products using the 37signals philosophy from "Getting Real", "Rework", and "Shape Up". Use when the user mentions "Getting Real", "Rework", "Shape Up", "37signals", "Basecamp method", "six-week cycles", "fixed time variable scope", "appetite vs estimates", "betting table", "breadboarding", "fat marker sketch", "build less", "underdo the competition", "opinionated software", "we have too many meetings", "how do we ship faster", or "stop overbuilding". Also trigger when cutting scope to ship sooner, running a small team, or avoiding long-term roadmaps. Covers shaping, betting, building, and the art of saying no. For MVP validation, see lean-startup. For design sprints, see design-sprint.' +license: MIT +metadata: + author: wondelai + version: "1.3.0" +--- + +# The 37signals Product Development Framework + +A system for building profitable software without bloat, bureaucracy, or burnout, distilled from three books: *Getting Real* (build less), *Rework* (say no by default), and *Shape Up* (fix time, flex scope). Use it to shape work, bet on six-week cycles, run small autonomous teams, and ship on a predictable cadence. + +## Core Principle + +**Build less.** The best products do fewer things exceptionally well — simplicity is the destination, not the starting point. Traditional development adds; the 37signals way subtracts: build half a product (not a half-assed product), say no by default, fix the time and flex the scope. Constraints are what make great work possible — six weeks, three people, and a shaped pitch force you to find the essential version. + +## Scoring + +**Goal: 10/10.** Rate product plans, feature scopes, and team processes 0-10 against these principles. Report the current score and the specific changes needed to reach 10/10. + +- **9-10:** Fixed-time cycles, shaped pitches, small teams, no backlog, opinionated defaults, clear copy +- **7-8:** Mostly shaped work and small teams, but some scope creep or process overhead +- **5-6:** Some shaping happens, but backlogs persist, teams are too large, or preferences replace decisions +- **3-4:** Heavy process (standups, sprints, story points) with occasional simplicity efforts +- **0-2:** Feature factory: long-term roadmaps, large teams, estimation rituals, no shaping + +### 1. Build Less, Underdo the Competition + +**Core concept:** Win through deliberate omission — fewer features, fewer preferences, fewer moving parts, each done better than competitors do theirs. Build software you need yourself and solve problems you understand deeply. + +**Why it works:** Every feature carries maintenance, cognitive, and opportunity costs forever, usually for a fraction of users. Building less keeps the product focused, the codebase manageable, and the team small. + +**Key insights:** +- Half a product beats a half-assed product — do a few things well, not many things poorly +- Be a curator, not a hoarder: say no to good ideas so the great ones can breathe +- Make tiny decisions — big ones are hard to make and hard to reverse; small ones build momentum +- Underdo the competition: let them build the Swiss Army knife while you build the steak knife +- Focus on what won't change — speed, simplicity, reliability, ease of use + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| **Feature prioritization** | Default answer is no | Reporting dashboard requested → ship CSV export covering 90% of use cases | +| **MVP scoping** | Cut until it hurts, then cut more | Drop user accounts for v1; use email magic links | +| **Competitive strategy** | Underdo, don't outdo | Competitor has 50 integrations; ship 3 that work flawlessly | + +See [references/build-less.md](references/build-less.md) when deciding what to cut — curation tactics, the constraints-as-feature argument, and worked scope-cut examples. + +### 2. Shaping the Work + +**Core concept:** Before work reaches a team, a senior person who bridges product and technical worlds makes it rough (room to maneuver), solved (main elements figured out), and bounded (scope limited by appetite). + +**Why it works:** Raw ideas waste team time; detailed specs turn teams into ticket-takers. Shaping removes the biggest unknowns while leaving design freedom, and appetite ("how much time is this worth?") replaces estimation ("how long will this take?") — bounded investment instead of open-ended commitment. + +**Key insights:** +- A shaped pitch has five elements: problem, appetite, solution, rabbit holes, no-gos +- Breadboard flows as places, affordances, and connections — structure without visual design +- Fat marker sketches keep abstraction high; wireframes invite pixel-level feedback before the concept is validated +- Rabbit holes (scope-blowing risks) get addressed in the pitch, not during the build +- No-gos make boundaries visible, preventing scope creep before it starts + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| **Feature design** | Breadboard before mockup | "Invite teammate": Settings → invite form → email sent → accept link → dashboard | +| **Scope definition** | Set appetite first | "A 2-week appetite problem, not a 6-week one" shapes which solution fits | +| **Risk management** | Call out rabbit holes upfront | "Permissions could get complex — limit to owner/member for v1" | + +**Ethical boundary:** Set appetites that reflect the problem's genuine value — never artificially small to pressure teams. + +See [references/shaping-work.md](references/shaping-work.md) when drafting a pitch — the five-element pitch format, a worked breadboard, fat-marker rules, the rabbit-hole pattern table, good/bad no-go examples, and a 6-step shaping procedure. + +### 3. Betting and Cycles + +**Core concept:** Replace backlogs and roadmaps with a betting table: senior stakeholders bet shaped pitches into six-week cycles, separated by two-week cool-downs. Unfinished work hits the circuit breaker — it does not automatically continue. + +**Why it works:** Backlogs grow forever, create false progress, and dilute focus; limited cycle slots force real prioritization. The circuit breaker kills zombie projects, and cool-downs prevent the burnout of continuous sprinting. + +**Key insights:** +- Abolish the backlog — if an idea is important, it will come back +- Six weeks is long enough for meaningful work, short enough to feel the deadline +- Variable scope: teams cut non-essential scope to hit the fixed deadline, never the reverse +- Plan one cycle at a time — long-term roadmaps are stale commitments +- Most pitches don't get bet on, and that's healthy + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| **Roadmap replacement** | Bet each cycle | 3-4 shaped pitches every 6 weeks instead of a 12-month roadmap | +| **Risk management** | Circuit breaker kills zombies | 70% done at week 6? It doesn't ship — re-shape and re-bet if it still matters | +| **Capacity planning** | Cool-down between cycles | Two weeks for bugs, tech debt, exploration, recovery | + +**Ethical boundary:** Apply the circuit breaker honestly — to kill zombies, not politically inconvenient projects; the point is focus, not unsustainable pressure. + +See [references/betting-cycles.md](references/betting-cycles.md) when running a betting table or planning a cycle — how the table decides, structuring the six-week/two-week rhythm, applying the circuit breaker, and the case against backlogs. + +### 4. Small Teams and Execution + +**Core concept:** Three-person teams (one designer, one or two programmers) work a shaped pitch autonomously — no standups, no PMs hovering. They discover their own tasks and track progress on hill charts. + +**Why it works:** Three people can have a conversation; ten need a meeting. Teams that discover tasks from a shaped pitch develop real problem understanding, and hill charts tell the truth: uphill = still figuring out, downhill = executing known work. + +**Key insights:** +- Scopes replace tasks — group related work into named slices that move independently on the hill +- Meetings are toxic: write it up instead +- Get real: working HTML with real data on day 2 beats a Figma mockup on day 5 +- Launch now, iterate later — software in users' hands beats plans in a deck +- Design and programming integrate from day one — no handoff phases + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| **Team structure** | Three people max, no PM | One designer + two programmers per 6-week bet | +| **Progress tracking** | Hill charts, not burndowns | "Invitations" uphill (permissions unclear); "Email templates" downhill (executing) | +| **Communication** | Async-first, write it up | A written update or 5-minute video instead of a 30-minute meeting | + +**Ethical boundary:** Autonomy requires genuinely manageable scope — if a team consistently works overtime to hit six weeks, fix the shaping, not the team. + +See [references/small-teams-execution.md](references/small-teams-execution.md) when a team is mid-build — reading and updating hill charts, slicing scopes, async communication norms, and getting real with working HTML. + +### 5. Opinionated Software and Clear Communication + +**Core concept:** Great software makes choices instead of burying users in preferences — every preference is a decision the team could not or would not make. The same honesty applies to copy: say what you mean, skip buzzwords, teach what you know openly. + +**Why it works:** Every added preference splits the product into more states to design, test, and support, and pushes a decision onto users who lack the context to make it well; sensible defaults reduce cognitive load and create cohesion. Clear copy builds trust where marketing-speak erodes it, and teaching openly attracts customers who share your values. + +**Key insights:** +- Pick the best default and ship it — revisit only if data shows it fails most users +- Epicycles (features patching problems earlier features created) compound complexity +- "Not now" is a valid, healthy answer to good feature requests +- Out-teach the competition; sell your by-products (books, posts, tools) +- Interface copy is your best marketing — every label and error message builds or burns trust + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| **Feature requests** | Default no, no false promises | "Thanks for the suggestion. We're not planning this right now." | +| **UI copy** | Plain language | "Your file is saved" not "Your asset has been successfully persisted to the cloud" | +| **Error messages** | Honest and helpful | "We couldn't send that email. Check the address and try again." | +| **Preferences** | Eliminate; choose defaults | Detect timezone from the browser; ship one good theme | +| **Marketing** | Honest positioning | "Basecamp is not for everyone. Here's who it's for and who it's not for." | + +See [references/opinionated-software.md](references/opinionated-software.md) when responding to feature requests or removing settings, and [references/ux-ui-copy.md](references/ux-ui-copy.md) when writing interface copy, empty states, or error messages. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Maintaining a backlog | Grows forever; false progress; diluted focus | Abolish it; bet on shaped pitches each cycle | +| Estimating instead of setting appetite | Estimates grow to fill time and invite negotiation | Ask "how much time is this problem worth?" | +| Pixel-perfect mockups before shaping | Too concrete too early; invites bikeshedding | Breadboards and fat marker sketches first | +| Extending a six-week cycle | Zombie projects teach teams deadlines are fake | Circuit breaker: not done means not shipped | +| Adding preferences instead of deciding | Complexity for all users to serve a few | Pick the best default and ship it | +| Daily standups and status meetings | Interrupt maker flow; reporting overhead | Hill charts for visibility; async updates | +| Saying yes to good feature requests | Good features still add non-essential complexity | Default to no; bet only on what matters this cycle | +| Planning multiple cycles ahead | Stale commitments reduce responsiveness | Plan one cycle at a time | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Is there a fixed time constraint on this work? | Scope expands indefinitely | Set a six-week (or smaller) appetite first | +| Is the work shaped (rough, solved, bounded)? | Scope problems surface mid-build | Define problem, appetite, solution, rabbit holes, no-gos | +| Can a team of 2-3 people do this? | Too big | Break into independent six-week bets | +| Said no to at least 5 things this cycle? | Building too much | Cut ruthlessly at the betting table | +| Is the team figuring out its own tasks? | Micromanagement; team not empowered | Hand off shaped pitches, not task lists | +| Tracking progress with hill charts? | False precision masks uncertainty | Switch to uphill (figuring out) vs. downhill (executing) | +| Is there a cool-down after this cycle? | Burnout; no cleanup time | Schedule two unstructured weeks between cycles | +| Does the software have a clear opinion here? | Decisions deferred to users via preferences | Pick the best default; remove the setting | + +See [references/case-studies.md](references/case-studies.md) for end-to-end worked scenarios when you want a model to follow — adopting Shape Up, resisting feature creep, and replacing status meetings with hill charts. + +## Further Reading + +- [*"Getting Real"*](https://www.amazon.com/Getting-Real-Smarter-Successful-Application/dp/0578012812?tag=wondelai00-20) by Jason Fried & David Heinemeier Hansson +- [*"Rework"*](https://www.amazon.com/Rework-Jason-Fried/dp/0307463745?tag=wondelai00-20) by Jason Fried & David Heinemeier Hansson +- [*"Shape Up: Stop Running in Circles and Ship Work that Matters"*](https://www.amazon.com/Shape-Up-Circles-Ship-Work/dp/B09ZSY1MWP?tag=wondelai00-20) by Ryan Singer +- [*"It Doesn't Have to Be Crazy at Work"*](https://www.amazon.com/Doesnt-Have-Crazy-Work/dp/0062874780?tag=wondelai00-20) by Jason Fried & David Heinemeier Hansson +- [*"Remote: Office Not Required"*](https://www.amazon.com/Remote-Office-Required-Jason-Fried/dp/0804137501?tag=wondelai00-20) by Jason Fried & David Heinemeier Hansson + +## About the Authors + +**Jason Fried** is co-founder and CEO of 37signals (Basecamp, HEY) and a leading advocate for calm companies and product simplicity. **David Heinemeier Hansson (DHH)** is 37signals co-founder and creator of Ruby on Rails, extracted from Basecamp's codebase; together they wrote *Getting Real*, *Rework*, *Remote*, and *It Doesn't Have to Be Crazy at Work*. **Ryan Singer** spent 15+ years shaping product at 37signals and codified the methodology in *Shape Up*. diff --git a/.agents/skills/37signals-way/references/betting-cycles.md b/.agents/skills/37signals-way/references/betting-cycles.md new file mode 100644 index 00000000..ee137cdd --- /dev/null +++ b/.agents/skills/37signals-way/references/betting-cycles.md @@ -0,0 +1,213 @@ +# Betting and Cycles + +## Table of Contents + +- [Why Not Backlogs](#why-not-backlogs) +- [The Betting Table](#the-betting-table) +- [Six-Week Cycles](#six-week-cycles) +- [The Circuit Breaker](#the-circuit-breaker) +- [Cool-Down Periods](#cool-down-periods) +- [Fixed Time, Variable Scope](#fixed-time-variable-scope) +- [Cycle Planning in Practice](#cycle-planning-in-practice) +- [When to Use Small Batches](#when-to-use-small-batches) + +## Why Not Backlogs + +A backlog is a growing list of ideas, requests, and tasks that theoretically represent future work. In practice, backlogs create more problems than they solve. + +**The problems with backlogs:** + +1. **Backlogs grow forever.** Items are added faster than they are completed. A 200-item backlog is not a plan — it is an anxiety list. + +2. **Backlogs create false obligations.** Once an idea is in the backlog, it feels like a commitment. Teams spend time grooming, prioritizing, and re-prioritizing items that may never be built. + +3. **Backlogs dilute focus.** When everything is in the backlog, nothing stands out. The important is buried alongside the trivial. + +4. **Backlogs discourage fresh thinking.** Instead of evaluating each cycle on its own merits, teams default to pulling from the backlog — recycling old ideas instead of responding to current reality. + +5. **Backlogs are emotionally draining.** Team members see hundreds of items and feel perpetually behind. The list never gets shorter. Morale suffers. + +**The 37signals alternative:** No backlogs. Ideas are either shaped into pitches and bet on for the next cycle, or they are let go. If an idea is truly important, it will come back — someone will bring it up again, or the problem will resurface. If it does not come back, it was not important enough to build. + +**But what about good ideas we might forget?** Some ideas do deserve to be saved. The key is who saves them and how. Individual team members can keep their own informal lists. A senior person can maintain a short list of potential pitches to shape. But there is no shared, groomed backlog that creates obligations for the team. + +## The Betting Table + +The betting table is a meeting that happens at the end of each cool-down period, before the next cycle begins. A small group of senior stakeholders reviews shaped pitches and decides which ones to bet on. + +**Who attends the betting table:** + +- The CEO or product owner (final decision authority) +- A senior technical person (can assess feasibility) +- A senior designer or product strategist (can assess solution quality) +- Optionally, one or two other senior people with relevant context + +This is not a democratic process. The betting table is small by design — 2-4 people, never more. Too many voices leads to compromise, and compromise produces mediocre bets. + +**How the betting table works:** + +1. **Review pitches.** The group reads the shaped pitches (written documents, not presentations). Each pitch takes 5-10 minutes to review. + +2. **Discuss trade-offs.** For each pitch, discuss: Is this the right problem? Is the appetite appropriate? Does the solution address the problem well enough? Are the rabbit holes handled? + +3. **Place bets.** Decide which pitches get a team for the next cycle. A bet means committing a team for 6 weeks. This is real commitment — once a bet is placed, the team is protected from interruption. + +4. **Say no to the rest.** Most pitches do not get bet on. This is healthy and expected. The rejected pitches are not added to a backlog — they are simply not bet on this cycle. + +**What makes a good bet:** + +| Factor | Strong Bet | Weak Bet | +|--------|-----------|----------| +| Problem clarity | Specific, concrete user scenario | Vague goal ("improve engagement") | +| Solution quality | Shaped, with breadboards and no-gos | Half-baked idea or unshaped request | +| Appetite match | Solution clearly fits the time budget | Solution seems too big or too uncertain | +| Strategic fit | Aligns with current business priorities | Nice-to-have with no urgency | +| Risk level | Rabbit holes identified and addressed | Major unknowns unresolved | + +## Six-Week Cycles + +Six weeks is the standard cycle length at 37signals. It is long enough for a small team to build something meaningful, and short enough to maintain urgency and limit the damage of a wrong bet. + +**Why six weeks, not two-week sprints:** + +- **Two weeks is too short** for meaningful work. Teams spend a disproportionate amount of time on planning, estimating, and ceremony relative to actual building. +- **Six weeks is long enough** for a designer and one or two programmers to build a significant feature from start to finish, including design, code, testing, and polish. +- **Six weeks creates natural urgency.** In the first week or two, the team explores the problem and discovers tasks. By week three, they should be executing. By week five, they should be cutting scope and converging. Week six is finish and polish. + +**Why not longer than six weeks:** + +- **Projects longer than six weeks lose urgency.** The deadline feels distant, and teams defer hard decisions. +- **Longer timelines increase risk.** The more time you invest before shipping, the more you lose if the bet was wrong. +- **Large projects should be broken into independent six-week bets.** If a feature genuinely needs 12 weeks, shape it into two independent six-week pieces, each of which delivers value on its own. + +**The rhythm of a six-week cycle:** + +| Week | Phase | Activity | +|------|-------|----------| +| 1 | Exploration | Team reads the pitch, explores the problem, discovers scopes | +| 2 | Exploration → Building | Scopes take shape, first code and design emerge | +| 3 | Building | Core functionality coming together, biggest uncertainties resolved | +| 4 | Building | Integration, edge cases, testing begins | +| 5 | Convergence | Scope cutting begins — what is not essential gets cut | +| 6 | Convergence → Ship | Polish, final testing, deployment | + +## The Circuit Breaker + +The circuit breaker is the most important and most controversial element of the 37signals methodology. It is simple: if a project is not done at the end of its six-week cycle, it does not automatically continue. It stops. + +**How the circuit breaker works:** + +1. A team is given a six-week bet. +2. At the end of six weeks, the work is either done or it is not. +3. If it is done, it ships. +4. If it is not done, it does not get an automatic extension. The project is paused and returned to the shaping table. +5. If the problem is still important, a new pitch is shaped (possibly re-scoped) and brought to the next betting table. It competes with other pitches on its merits. + +**Why the circuit breaker exists:** + +- **Prevents zombie projects.** Without a circuit breaker, projects in trouble get extensions, then more extensions, consuming resources while delivering diminishing returns. +- **Forces honest shaping.** If you know the circuit breaker is real, you shape more carefully. You cut scope more aggressively. You identify rabbit holes more diligently. +- **Protects team morale.** Struggling teams are freed from death marches. A fresh start with better shaping is more humane and more effective than grinding through. +- **Keeps the betting table honest.** When bets that do not pay off are stopped, stakeholders take the betting process more seriously. + +**When to invoke the circuit breaker:** + +- The team has significant unfinished work that cannot be completed with a few extra days +- The core approach turned out to be wrong and needs re-thinking +- New information has changed the value of the project +- The team is demoralized and grinding rather than building with momentum + +**When not to invoke it:** + +- The work is 90%+ complete and needs only a few days of polish — some flexibility is reasonable +- External dependencies (not the team's fault) caused delays — address the dependency issue separately + +**Common objections and responses:** + +| Objection | Response | +|-----------|----------| +| "We'll lose all the work we did" | The code and knowledge remain. The next pitch can build on what was learned. | +| "It will demoralize the team" | Extending a struggling project is more demoralizing. A fresh start is a gift. | +| "We're so close, just one more week" | If one more week would fix it, the team would have found that scope cut during week 5. | +| "The customer is waiting" | Better to re-shape and deliver something good than to ship something half-finished. | + +## Cool-Down Periods + +Between every six-week cycle, there is a two-week cool-down period. This is not vacation time, but it is unstructured time — no assigned projects, no obligations, no pressure. + +**What happens during cool-down:** + +- **Bug fixes.** Small bugs that accumulated during the cycle get addressed. +- **Exploration.** Team members pursue ideas that interest them — potential future pitches, new technology experiments, side projects. +- **Technical maintenance.** Dependency updates, infrastructure improvements, small refactors. +- **Recovery.** After six weeks of focused building, people need time to decompress and reset. + +**Why cool-down matters:** + +- **Prevents burnout.** Back-to-back cycles with no breaks create unsustainable pace. +- **Creates slack for emergencies.** If something urgent arises, the cool-down absorbs it without disrupting a cycle. +- **Generates fresh ideas.** Unstructured time produces the insights and experiments that become future pitches. +- **Maintains quality.** Technical debt accumulates during focused cycles; cool-down is when it gets addressed. + +**Cool-down is also when the betting table meets.** Senior people use the cool-down to review shaped pitches, discuss priorities, and decide what to bet on for the next cycle. + +## Fixed Time, Variable Scope + +This is the fundamental inversion that makes the 37signals methodology work. Traditional projects fix the scope and let the timeline flex. Shape Up fixes the timeline and lets the scope flex. + +**How scope flexing works:** + +1. A team receives a shaped pitch with a six-week appetite. +2. During weeks 1-2, they explore the pitch and discover scopes (named chunks of work). +3. During weeks 3-4, they build the core scopes. +4. During weeks 5-6, they evaluate remaining scopes. Nice-to-haves that do not fit are cut. Must-haves get the remaining time. +5. At the end of week 6, whatever is done ships. Whatever was cut was either not essential or can be addressed in a future bet. + +**What makes scope cutting work:** + +- **The pitch defines what is essential.** The shaped solution identifies the core problem and the core flow. Everything else is negotiable. +- **No-gos set explicit boundaries.** Things that are already excluded in the pitch cannot creep back in. +- **The team has autonomy.** Because the team discovered their own scopes, they understand which ones are essential and which are nice-to-have. They can make intelligent cut decisions. + +**The beauty of variable scope:** When you fix the time and flex the scope, every bet has a bounded downside. The worst case is six weeks of work with a reduced scope shipped. The best case is the full solution in six weeks. Either way, the team moves on to the next cycle with a fresh start. + +## Cycle Planning in Practice + +**Before the cycle (cool-down period):** + +1. Shapers prepare pitches for problems worth solving +2. Pitches are shared as written documents for asynchronous review +3. The betting table meets to review pitches and place bets +4. Bets are communicated to teams with the full shaped pitch + +**During the cycle (six weeks):** + +1. Week 1: Team reads the pitch, explores the territory, identifies scopes +2. Week 2: Scopes solidify, uphill work on biggest unknowns begins +3. Weeks 3-4: Core building, scopes move downhill, integration happens +4. Week 5: Scope cutting decisions, convergence begins +5. Week 6: Polish, testing, deployment + +**After the cycle:** + +1. Work ships (or the circuit breaker fires) +2. Cool-down begins — two weeks of unstructured time +3. The cycle repeats + +## When to Use Small Batches + +Not everything needs a six-week cycle. Small batches (1-2 week projects) are appropriate for: + +- Bug fixes that need more than a quick patch +- Small improvements that users have been requesting +- Experiments or proofs of concept +- Internal tooling improvements + +**How small batches fit the cycle:** + +- Small batches are also bet on at the betting table +- Multiple small batches can run in a single cycle (one team does 3-4 small projects in six weeks) +- Small batches still have a fixed time constraint — 1-2 weeks per project +- The circuit breaker still applies — if a "1-week project" is not done in 1 week, stop and re-evaluate + +**The key distinction:** Small batches are for work that is already well-understood and does not need extensive shaping. If a small project keeps growing, it probably needs to be shaped as a full six-week bet instead. diff --git a/.agents/skills/37signals-way/references/build-less.md b/.agents/skills/37signals-way/references/build-less.md new file mode 100644 index 00000000..d0fbc817 --- /dev/null +++ b/.agents/skills/37signals-way/references/build-less.md @@ -0,0 +1,154 @@ +# Build Less: The Philosophy of Deliberate Omission + +## Table of Contents + +- [The Core Argument](#the-core-argument) +- [Underdo the Competition](#underdo-the-competition) +- [Solve Your Own Problem](#solve-your-own-problem) +- [Embrace Constraints](#embrace-constraints) +- [Be a Curator](#be-a-curator) +- [Half a Product, Not a Half-Assed Product](#half-a-product-not-a-half-assed-product) +- [Focus on What Won't Change](#focus-on-what-wont-change) +- [The Feature Audit](#the-feature-audit) +- [Practical Application](#practical-application) + +## The Core Argument + +Most software fails not because it does too little, but because it does too much. Every feature added to a product carries hidden costs: maintenance burden, cognitive load for users, increased testing surface, documentation overhead, and opportunity cost. The 37signals philosophy inverts the default: instead of asking "What should we add?", ask "What can we leave out?" + +This is not minimalism for its own sake. It is a strategic choice rooted in the reality of building products with small teams and limited resources. When you build less, you can build better. When you maintain less, you can move faster. When users have fewer choices, they make decisions more confidently. + +Getting Real calls this "less software." Rework calls it "underdoing the competition." Both mean the same thing: the constraint of less is not a limitation — it is the competitive advantage. + +## Underdo the Competition + +The instinct when facing a competitor with more features is to match them. This is a trap. Feature parity is an arms race that favors incumbents with bigger teams and deeper pockets. The 37signals alternative: do less, but do it so well that the simplicity itself becomes the selling point. + +**How underdoing works:** + +- Competitor has 50 integrations? You ship 3 that work flawlessly and require zero configuration. +- Competitor has a full project management suite? You ship task lists with clear deadlines and nothing else. +- Competitor has 20 report types? You ship one report that answers the question 80% of users actually have. + +Underdoing is not laziness. It requires harder decisions than overdoing. You must understand which 20% of functionality delivers 80% of the value, and have the discipline to ship only that. + +**The psychology of underdoing:** Users experience feature overload as anxiety. A product with fewer, better features feels more trustworthy than one with dozens of half-implemented ones. Simplicity signals confidence — it says "we know what matters." + +**When underdoing fails:** Underdoing fails when you cut core functionality, not peripheral features. The key is understanding the essential job your product does. A project management tool can skip Gantt charts but cannot skip task assignment. Know the job, then strip everything that does not directly serve it. + +## Solve Your Own Problem + +The surest way to build something valuable is to build something you need yourself. When you are your own user, you understand the problem intimately. You do not need extensive user research to know if a feature works — you use it every day. You do not need a PM to prioritize — your own frustration tells you what matters. + +**Why self-use matters:** + +- **Faster feedback loops.** You notice problems immediately because you experience them. +- **Authentic understanding.** You know the difference between nice-to-have and must-have because you feel it. +- **Reduced research overhead.** User interviews supplement your understanding rather than being your only source. +- **Better taste.** You develop strong opinions about how things should work because you live with the consequences. + +Basecamp was built because 37signals needed a project management tool for their own client work. Ruby on Rails was extracted from Basecamp's codebase. HEY was built because they were frustrated with existing email clients. In each case, the product existed to solve a real problem the team experienced daily. + +**The limitation:** Solving your own problem works best when your problem is shared by many others. It fails when your use case is too niche or idiosyncratic. The check: would at least a few thousand other people recognize this problem as their own? + +## Embrace Constraints + +Constraints — limited time, limited budget, limited people — are typically viewed as obstacles. The 37signals philosophy treats them as creative fuel. When you cannot do everything, you must find the essential version. When you have three people instead of thirty, you cannot afford unnecessary complexity. When you have six weeks instead of six months, you must cut to what matters. + +**Types of constraints and their creative benefits:** + +| Constraint | What It Forces | Creative Benefit | +|-----------|----------------|-----------------| +| Small team (2-3 people) | No specialization overhead, direct communication | Every person understands the whole; decisions happen fast | +| Fixed time (6 weeks) | Cannot build everything | Must find the simplest version that delivers value | +| No outside funding | Must be profitable early | Forces focus on features users will pay for, not vanity metrics | +| No dedicated PM role | Team owns decisions | No telephone game between decision-makers and builders | +| Simple technology stack | Cannot over-engineer | Solutions are maintainable and debuggable by the whole team | + +**The paradox of constraints:** Teams with unlimited resources often ship slower and worse than teams with tight constraints. Abundance breeds indecision — when you can do anything, you debate endlessly about what to do. Scarcity breeds action — when you can only do one thing, you pick it and move. + +## Be a Curator + +Building software requires a curator — someone who decides what stays and what goes. Like a museum curator who selects which pieces belong in an exhibit, a product curator decides which features belong in the product. The curator's most important tool is the word "no." + +**What curators do:** + +- **Say no by default.** The default response to any feature request, any idea, any suggestion is no. Only the ideas that keep coming back, that solve real problems, that fit the product's opinion get through. +- **Remove, not just add.** Curators periodically audit the product and remove features that no longer earn their place. If a feature is rarely used and adds maintenance cost, it goes. +- **Maintain coherence.** A product with 100 well-curated features feels simple. A product with 20 random features feels complex. Coherence comes from having a clear opinion about what the product is for. +- **Resist epicycles.** An epicycle is a feature added to fix a problem caused by an earlier feature. Epicycles compound complexity. When you notice an epicycle forming, remove the root cause rather than adding another layer. + +**The feature request trap:** Users request features that solve their immediate problem without considering the systemic cost. "Just add an option for X" sounds simple but adds one more preference, one more test path, one more thing to document. The curator's job is to understand the underlying need and find a solution that serves it without adding complexity. + +## Half a Product, Not a Half-Assed Product + +This is the most frequently quoted 37signals principle, and the most frequently misunderstood. It does not mean "ship something broken." It means: deliberately choose to build a complete, polished version of half the features rather than a half-finished version of all the features. + +**What "half a product" looks like:** + +- Every feature that ships works correctly, is well-designed, and is properly documented +- The product does fewer things but does each one with care and attention +- Users can accomplish the core job without workarounds or missing pieces +- The product feels finished, not like a beta + +**What "half-assed" looks like:** + +- Many features exist but most are partially implemented or buggy +- The product technically has a feature checklist but users hit walls constantly +- Edge cases are unhandled, error states are unhelpful, and flows are inconsistent +- The product feels unfinished despite being feature-rich on paper + +**The decision framework:** Before adding a feature, ask: "If we add this, can we do it completely and well within our constraints?" If the answer is no, do not add it. A missing feature is invisible. A broken feature is visible and damaging. + +## Focus on What Won't Change + +Rework makes a sharp distinction between what changes (trends, technologies, competitors' features) and what does not change (speed, simplicity, reliability, ease of use, quality). The 37signals bet: invest in what will not change, because those investments compound forever. + +**What does not change:** + +- Users want software that is fast +- Users want software that is simple to understand +- Users want software that works reliably +- Users want clear communication (no jargon, no hidden surprises) +- Users want to accomplish their task with minimum friction + +**What changes constantly:** + +- Technology stacks and frameworks +- Design trends and visual styles +- Competitor feature sets +- Market narratives and buzzwords + +Building on what does not change means your investment appreciates. Building on what changes means your investment depreciates. + +## The Feature Audit + +Periodically audit your product to identify features that no longer earn their place. Use this decision matrix: + +| Feature State | Usage | Maintenance Cost | Action | +|--------------|-------|-----------------|--------| +| Core — defines the product | High | Any | Keep and invest | +| Useful — supports the core job | Moderate | Low | Keep | +| Useful — supports the core job | Moderate | High | Simplify or rebuild | +| Marginal — nice-to-have | Low | Low | Keep for now, monitor | +| Marginal — nice-to-have | Low | High | Remove | +| Legacy — served a past need | Minimal | Any | Remove | +| Epicycle — fixes problems from other features | Any | Any | Remove root cause instead | + +**How to run the audit:** + +1. List every feature in the product +2. Classify each by usage level and maintenance cost +3. Identify epicycles — features that exist only because of other features +4. Propose removals and simplifications +5. Ship the leaner version and measure impact + +## Practical Application + +**For product managers:** When prioritizing, start by asking "What can we remove?" before "What should we add?" Every removal simplifies the product for all users. Every addition complicates it for all users. + +**For designers:** Design the simplest possible version first. Add elements only when their absence causes a real problem, not a theoretical one. If you are designing preferences, stop and ask which default would work for 80% of users. + +**For engineers:** Resist the urge to build for hypothetical future requirements. Build what is needed now, build it well, and trust that you can extend it later if the need materializes. The best code is code you do not write. + +**For founders:** Your competitive advantage is not features — it is focus. The company with fewer features and a clearer opinion will always out-execute the company trying to be everything to everyone. diff --git a/.agents/skills/37signals-way/references/case-studies.md b/.agents/skills/37signals-way/references/case-studies.md new file mode 100644 index 00000000..349de112 --- /dev/null +++ b/.agents/skills/37signals-way/references/case-studies.md @@ -0,0 +1,228 @@ +# Case Studies: 37signals Principles in Practice + +## Table of Contents + +- [Case Study 1: From Scrum to Shape Up](#case-study-1-from-scrum-to-shape-up) +- [Case Study 2: Resisting Feature Creep](#case-study-2-resisting-feature-creep) +- [Case Study 3: Replacing Status Meetings with Hill Charts](#case-study-3-replacing-status-meetings-with-hill-charts) +- [Key Takeaways](#key-takeaways) + +## Case Study 1: From Scrum to Shape Up + +### Context + +A 25-person B2B SaaS company builds project management software for construction firms. They have been running two-week Scrum sprints for three years. The team consists of 4 product managers, 12 engineers, 3 designers, and 6 people in other roles (QA, DevOps, support). + +### The Problems + +**Sprint planning consumed 20% of productive time.** Every two weeks, the team spent a full day on sprint planning: grooming the backlog, estimating story points, debating priorities, assigning tasks. With two-week sprints, this meant one day out of every ten was spent on ceremony rather than building. + +**The backlog had 847 items.** Over three years, the backlog had grown from a focused list to an unmanageable graveyard. The team spent hours each month grooming items they would never build. The backlog created a constant sense of being behind — there was always more to do than could ever be done. + +**Teams did not feel ownership.** Engineers received assigned tasks with detailed acceptance criteria. They executed the tasks but did not feel connected to the problems they were solving. Designer mockups were handed off to engineers who implemented them without understanding the design decisions. The result: technically correct but uninspired work. + +**Projects regularly overran.** Despite careful estimation with story points, projects consistently took 1.5x to 3x longer than estimated. Extensions were the norm. "One more sprint" became a running joke. + +### The Transition + +**Phase 1: Abolish the backlog (Week 1)** + +The product team exported the backlog to a spreadsheet (for reference, not obligation) and deleted it from the project management tool. The emotional reaction was mixed: some team members felt liberated, others felt anxious about losing their "to-do list." The leadership communicated clearly: "If something is important, it will come back. If it doesn't come back, we didn't need it." + +**Phase 2: Learn to shape (Weeks 2-6)** + +The two most senior product people (a PM and a designer) spent four weeks learning to shape. They read Shape Up, practiced breadboarding, and shaped three pitches as exercises. Key learnings: +- Shaping is harder than it looks — it requires holding business context, user needs, and technical reality simultaneously +- The appetite concept was the biggest mental shift: "How much is this worth?" instead of "How long will this take?" +- Breadboarding felt awkward at first but proved effective at clarifying flows without getting stuck on visual details + +**Phase 3: First six-week cycle (Weeks 7-12)** + +Three teams of three (one designer + two engineers) were formed. Each team received one shaped pitch. The remaining engineers handled small batch work (bug fixes, minor improvements) during the same cycle. + +Results of the first cycle: +- Two of three teams shipped successfully within six weeks +- One team hit the circuit breaker — their project was not done and was paused +- The team that hit the circuit breaker initially resisted, but after reflecting, agreed the pitch needed reshaping (the rabbit holes were larger than anticipated) +- Total ceremony time dropped from 20% to approximately 3% (one betting table meeting every 8 weeks) + +**Phase 4: Iterate and stabilize (Cycles 2-4)** + +Over the next three cycles (18 weeks), the company refined their approach: +- Shaping improved — rabbit holes were caught earlier, appetites were more realistic +- Teams learned to cut scope proactively rather than requesting extensions +- Hill charts replaced standup meetings — the team posted updates twice per week +- The circuit breaker fired once more, and the team handled it without drama + +### Results After 6 Months + +| Metric | Before (Scrum) | After (Shape Up) | +|--------|---------------|-----------------| +| Planning overhead | ~20% of time | ~3% of time | +| Backlog size | 847 items | None (abolished) | +| Projects completed on time | ~40% | ~75% (within fixed cycles) | +| Team satisfaction (survey) | 6.2/10 | 8.1/10 | +| Features shipped per quarter | ~8 | ~10 (with better quality) | +| Time spent in meetings | ~8 hrs/week/person | ~2 hrs/week/person | + +### Lessons Learned + +1. **The backlog deletion was the hardest step emotionally but the most impactful practically.** Once the list was gone, the team stopped feeling perpetually behind. +2. **Shaping is a skill that takes practice.** The first shaped pitches were too vague. By cycle 3, they were consistently high quality. +3. **The circuit breaker must be applied consistently.** When the team first hit it, there was pressure to extend. Holding the line established credibility. +4. **Not every team adapts at the same speed.** Some engineers thrived with autonomy immediately; others needed a cycle or two to adjust to discovering their own tasks. + +## Case Study 2: Resisting Feature Creep + +### Context + +A 10-person startup builds an email marketing tool for small businesses. After two years, the product has grown from a simple "create and send newsletters" tool to a complex platform with automation workflows, A/B testing, landing page builder, CRM, and advanced analytics. The team is struggling to maintain everything and shipping new features has slowed to a crawl. + +### The Problems + +**Every customer conversation added features.** Sales calls ended with "They'd sign up if we had X." Support tickets became feature requests. The team treated every request as a mandate, adding features without removing anything. + +**Complexity was compounding.** The automation workflow builder interacted with the CRM which interacted with the landing page builder which interacted with the analytics. Changing anything required understanding everything. Bug fixes in one area caused regressions in another. + +**New users were overwhelmed.** The onboarding flow required 12 steps. New users had to configure their CRM fields, set up automation rules, and connect their landing pages before they could send a single email. Activation rate had dropped from 60% to 28%. + +**The core product was neglected.** The email editor — the thing every user needed — had not been improved in 8 months. All engineering time went to maintaining peripheral features or building new ones. + +### The Intervention + +The founders read Getting Real and Rework and decided to apply the "build less" philosophy retroactively. + +**Step 1: Identify the core job** + +They surveyed users with one question: "What is the one thing you use our product for?" 73% of responses mentioned some variation of "send emails to my list." Not automation, not CRM, not landing pages — sending emails. + +**Step 2: Audit every feature** + +They categorized every feature using the feature audit framework: + +| Feature | Usage | Maintenance Cost | Decision | +|---------|-------|-----------------|----------| +| Email editor | High | Medium | Invest heavily | +| Subscriber management | High | Low | Keep, improve | +| Campaign scheduling | High | Low | Keep | +| Basic analytics (open/click) | High | Low | Keep | +| Automation workflows | Low (8% of users) | Very high | Remove | +| A/B testing | Low (5% of users) | Medium | Remove | +| Landing page builder | Low (3% of users) | High | Remove | +| CRM | Low (6% of users) | Very high | Remove | +| Advanced analytics | Low (4% of users) | Medium | Remove | + +**Step 3: Cut** + +They removed the automation workflow builder, the A/B testing feature, the landing page builder, the CRM module, and advanced analytics. This was painful — these features had taken months to build. But each one was used by fewer than 10% of customers and cost disproportionate engineering time to maintain. + +They communicated the changes to affected users with honesty: "We're focusing on making the core email experience excellent. These features are being retired. Here are alternatives that specialize in [automation/CRM/landing pages]. We'll help you export your data." + +**Step 4: Reinvest in the core** + +With 60% of their codebase removed, the team spent two six-week cycles rebuilding the email editor, simplifying the onboarding (from 12 steps to 3), and making the core sending workflow faster and more reliable. + +### Results After 4 Months + +| Metric | Before | After | +|--------|--------|-------| +| Codebase size | ~180K lines | ~75K lines | +| Feature count | 14 | 5 | +| Onboarding steps | 12 | 3 | +| Activation rate | 28% | 64% | +| Customer churn | 6.2%/month | 3.8%/month | +| Bug reports per week | ~22 | ~5 | +| Time to ship a new improvement | 4-6 weeks | 1-2 weeks | +| Engineering time on maintenance | ~55% | ~20% | + +### Lessons Learned + +1. **Removing features is harder socially than technically.** The code deletion was easy; explaining it to affected customers was hard but necessary. +2. **A small percentage of vocal users drove most feature requests.** The 8% who used automation were the loudest, but the 92% who just wanted good email tools were the majority. +3. **Simplification improved everything.** Fewer features meant fewer bugs, faster development, easier onboarding, and lower churn. The product was better in every measurable way. +4. **You can always add later.** The fear was that removing features was permanent. In reality, the team retained the option to re-add features as independent, well-shaped bets if demand justified it. So far, demand has not. + +## Case Study 3: Replacing Status Meetings with Hill Charts + +### Context + +A 15-person design and engineering team at a mid-size company builds internal tools. They have weekly one-hour status meetings where each of the 5 project leads presents their progress. In addition, there are daily 15-minute standups per team (3 teams, 15 minutes each). + +### The Problems + +**Status meetings were theater.** Project leads spent 30 minutes preparing slides for the weekly meeting. During the meeting, most attendees listened passively while one person presented. The information was stale by the time it was shared — things had changed since the slides were prepared. + +**"Percentage complete" was meaningless.** Project leads reported progress as percentages: "We're 70% done." But 70% done could mean "the easy 70% is done and the hard 30% remains" or "we're 70% through the timeline but only 40% through the complexity." Percentages created a false sense of precision. + +**Daily standups were ritualistic.** Team members recited "what I did yesterday, what I'll do today, any blockers" without genuine engagement. The standup ran on autopilot — it was a habit, not a tool. Real problems were discussed after the standup, in smaller groups. + +**Problems were hidden until late.** Because percentage-complete tracked tasks (not understanding), a scope that was "on track" could suddenly be "in trouble" when the team hit an unexpected complexity. The status meeting format did not surface this risk early enough. + +### The Transition + +**Week 1: Introduce hill charts** + +The team adopted hill charts for all active projects. Each project identified 4-8 scopes and placed them on the hill. Initial positions: + +- Most scopes started on the left side of the hill (uphill — still figuring things out) +- A few scopes started near the summit or on the downhill side (approach was clear) + +**Week 2: Replace standup with async updates** + +Daily standups were replaced with twice-weekly hill chart updates. Each team updated their hill chart positions and optionally wrote a one-paragraph note for any scope that moved significantly or got stuck. + +**Week 3: Replace weekly status meeting with hill chart review** + +The one-hour weekly status meeting was replaced with a 20-minute hill chart review. Instead of presentations, the group looked at the hill charts and focused only on scopes that were: +- Stuck uphill for more than a week (risk signal) +- Moving backward (the team discovered something harder than expected) +- Missing from the chart (a scope the team had not started yet) + +### How Hill Charts Changed the Conversation + +**Before (percentage-complete):** + +> "The reporting feature is about 60% complete. We're on track." +> "Great, any blockers?" +> "No blockers right now." +> (Two weeks later: "Actually, the reporting feature is going to need another sprint. We hit some complexity with the data aggregation layer.") + +**After (hill charts):** + +> "The 'Report Templates' scope is moving downhill — we know what to build and we're executing. But 'Data Aggregation' has been uphill for a week. We're still figuring out how to handle cross-timezone calculations." +> "That's a risk. Is the appetite still right for this, or does 'Data Aggregation' need to be re-scoped?" +> "Let's simplify — what if we only support one timezone per report for v1?" +> "That works. Move it to the summit." + +The hill chart made the risk visible two weeks earlier and prompted a scope-cutting conversation that kept the project on track. + +### Results After 3 Months + +| Metric | Before | After | +|--------|--------|-------| +| Time in status meetings per week | 3.25 hrs/person (1hr weekly + 0.75hr standups) | 0.5 hrs/person (20min review + 10min async updates) | +| Time to surface a stuck scope | 1-2 weeks (at next status meeting) | 2-3 days (next hill chart update) | +| "Surprise" project problems per quarter | 4-5 | 0-1 | +| Meeting preparation time per week | 30 min (slides) | 2 min (drag dots) | +| Sense of progress (team survey) | "We report progress" | "We see progress" | + +### What Made It Work + +1. **Hill charts separate uncertainty from execution.** The uphill/downhill distinction gives an honest view of where the real risk is, which percentage-complete cannot. +2. **Async updates respect focus time.** Writing a one-paragraph update takes 2 minutes and does not interrupt anyone's flow. A standup interrupts everyone's morning. +3. **Short meetings focus on risk, not reports.** The 20-minute review only discusses scopes that are stuck or moving backward. Good news is visible on the chart — it does not need to be presented. +4. **Visual progress is motivating.** Seeing scopes move across the hill provides a tangible sense of progress that task lists and percentages do not. + +## Key Takeaways + +Across all three case studies, several themes emerge: + +**1. Simplification improves outcomes.** In every case, removing process, removing features, or removing meetings led to better results. The instinct to add more is almost always wrong. + +**2. Honesty enables speed.** Hill charts show real risk. Appetite forces honest scoping. The circuit breaker forces honest assessment of progress. When the team is honest about where things stand, problems are caught early and addressed quickly. + +**3. Autonomy produces better work.** Teams that discover their own tasks, cut their own scope, and manage their own progress do better work than teams that follow instructions. Autonomy requires trust, and trust requires boundaries (shaped pitches, appetites, hill charts). + +**4. Transitions are uncomfortable.** Every team experienced discomfort when changing their process. The backlog deletion felt risky. The first circuit breaker felt harsh. Removing status meetings felt like losing control. In every case, the discomfort faded within one or two cycles as the new approach proved itself. + +**5. The framework adapts to context.** No team implemented Shape Up exactly as described in the book. Each adapted the principles to their size, domain, and culture. The six-week cycle is not sacred — the principles behind it (fixed time, variable scope, shaped work, small teams) are what matter. diff --git a/.agents/skills/37signals-way/references/opinionated-software.md b/.agents/skills/37signals-way/references/opinionated-software.md new file mode 100644 index 00000000..8a5b8b8c --- /dev/null +++ b/.agents/skills/37signals-way/references/opinionated-software.md @@ -0,0 +1,205 @@ +# Opinionated Software and Clear Communication + +## Table of Contents + +- [What Opinionated Software Means](#what-opinionated-software-means) +- [Defaults Over Preferences](#defaults-over-preferences) +- [The Epicycle Trap](#the-epicycle-trap) +- [The Art of Saying No](#the-art-of-saying-no) +- [Clear Copywriting Principles](#clear-copywriting-principles) +- [Focus on What Won't Change](#focus-on-what-wont-change) +- [Out-Teach the Competition](#out-teach-the-competition) +- [Sell Your By-Products](#sell-your-by-products) + +## What Opinionated Software Means + +Opinionated software makes choices on behalf of the user. Instead of offering 15 configuration options, it picks the best one and ships it as the default — or the only option. Instead of supporting every possible workflow, it supports one workflow well and says "this is how we think it should be done." + +This is the opposite of the "platform" mindset, where the goal is maximum flexibility. The 37signals mindset is: flexibility is complexity. Every option you add is a decision the user must make. Every configuration is a potential source of confusion. Opinionated software trades flexibility for clarity. + +**Examples of opinionated decisions in Basecamp:** + +| Area | Opinionated Choice | What They Did Not Build | +|------|-------------------|----------------------| +| Project structure | All projects have a message board, to-do lists, schedule, docs, and campfire chat | Custom project templates, configurable modules | +| Notifications | Sensible defaults with one toggle (on/off) per project | Per-event notification rules, notification schedules, do-not-disturb windows | +| Permissions | Simple owner/member model | Role-based access control, custom permission levels | +| File organization | Flat list with search | Folder hierarchies, tagging systems, metadata | +| Reporting | Built-in views that answer the most common questions | Custom report builder, query language, data export scheduler | + +**The cost of having no opinion:** Software without opinions becomes a configuration puzzle. Users spend more time setting up the tool than using it. Support teams answer the same questions about which settings to use. And the product loses its identity — it becomes a generic platform rather than a tool that stands for something. + +## Defaults Over Preferences + +Every preference in your software represents a decision your team did not make. Some of these are legitimate — users genuinely have different needs. But most preferences exist because the team could not decide, or because one vocal user requested an option, or because "we'll just make it configurable" felt easier than choosing. + +**The preference audit:** + +For each preference or setting in your product, ask: + +1. **What percentage of users change this from the default?** If it is less than 5%, remove the preference and keep the default. +2. **Is there a single best answer?** If yes, pick it and remove the option. Users do not want to choose — they want it to work. +3. **Does this preference exist because of a vocal minority?** One customer's request is not a mandate. Solve their specific problem differently. +4. **Does this preference create downstream complexity?** If a setting changes behavior in ways that affect other features, the complexity cost is high. Remove it. +5. **Would removing this break a significant use case?** If yes, keep it. If no, remove it. + +**How to pick good defaults:** + +- **Observe real behavior.** If you already have the preference, look at what most users choose. Make that the default. +- **Choose the safe option.** When in doubt, default to the option that is least likely to cause problems. +- **Choose the simple option.** When both options are safe, choose the one that requires less explanation. +- **Match user expectations.** What would a new user expect this to do without reading documentation? Do that. + +**Example: Timezone settings.** Most software asks users to set their timezone. 37signals approach: detect the timezone from the browser. If you are wrong, the user can change it — but you should not make every user manually configure something that can be detected automatically. + +## The Epicycle Trap + +An epicycle is a feature added to fix a problem caused by an earlier feature. The term comes from Ptolemaic astronomy, where epicycles (circles upon circles) were added to explain planetary motion within a flawed model. In software, epicycles look like this: + +1. You add a feature (bulk notifications) +2. Users complain it is noisy (because bulk notifications create too many alerts) +3. You add a preference to control notification frequency (epicycle 1) +4. Some users set it wrong and miss important notifications +5. You add a "priority notification" override (epicycle 2) +6. Users are now confused about the interaction between frequency settings and priority overrides +7. You add a documentation page explaining the notification system (epicycle 3) + +Each epicycle makes the original problem worse by adding complexity. The 37signals solution: remove the root cause. If bulk notifications are noisy, fix the notification logic — do not add settings to let users manage the noise themselves. + +**How to spot epicycles:** + +- You are adding a feature whose primary purpose is to manage or configure another feature +- You are writing documentation to explain feature interactions +- Users need a "getting started guide" for a single feature +- You are adding an "advanced settings" panel +- A feature has more than two preferences + +**How to break the cycle:** + +1. Identify the root feature that caused the downstream complexity +2. Ask: "Is there a simpler version of this root feature that would not need the epicycles?" +3. Replace the complex version with the simple one +4. Remove all the epicycles + +## The Art of Saying No + +Saying no is the most important skill in product development. Every feature request, no matter how reasonable, competes with simplicity. The default answer to any request must be no — not because the idea is bad, but because the cost of yes is always higher than it appears. + +**The hidden costs of yes:** + +| Visible Cost | Hidden Cost | +|-------------|------------| +| Development time | Maintenance forever | +| Design work | Cognitive load for all users | +| Testing effort | Documentation and support burden | +| One-time feature | Ongoing compatibility with future features | +| Satisfying one user | Complicating the product for everyone | + +**How to say no effectively:** + +- **Be direct.** "We're not going to build this" is clearer and kinder than "We'll add it to the backlog" (which is a lie). +- **Do not apologize.** You are making a product decision, not committing a wrong. "Thanks for the suggestion. We've decided not to include this." is sufficient. +- **Explain your reasoning (briefly).** "We want to keep the notification system simple, and this would add a level of complexity we're not comfortable with." One sentence, not a paragraph. +- **Do not promise a future.** "Not now" implies "later." If you mean no, say no. +- **Acknowledge the need.** "I understand this would be useful for your workflow" shows empathy without creating commitment. + +**When to say yes:** Say yes when a request solves a problem that many users share, aligns with the product's opinion, can be built simply, and fits within a cycle's appetite. That combination is rare — which is why no is the default. + +**The "few vocal users" problem:** A small number of power users generate a disproportionate amount of feature requests. Their needs are real but not representative. Building for vocal power users at the expense of the quiet majority is a common product mistake. The check: how many users does this actually affect? + +## Clear Copywriting Principles + +The 37signals approach to copy is an extension of their product philosophy: simple, honest, and opinionated. Every word in the interface is a product decision. + +**The rules:** + +**1. Write for humans, not for marketers.** If a sentence would sound weird spoken aloud in a conversation, rewrite it. "Your file has been saved" is human. "Your asset has been successfully persisted to our cloud infrastructure" is not. + +**2. No buzzwords.** Remove every instance of: "leverage," "synergy," "seamless," "robust," "cutting-edge," "next-generation," "holistic," "ecosystem," and any word that means nothing specific. Replace with plain language. + +**3. Be specific.** "Fast" is vague. "Loads in under 2 seconds" is specific. "Easy to use" is vague. "Set up in 3 steps" is specific. Specificity builds trust; vagueness erodes it. + +**4. Be honest about limitations.** If your product does not do something, say so. "Basecamp is not for everyone. Here's who it's for." This honesty attracts the right customers and repels the wrong ones — both good outcomes. + +**5. Error messages are a product.** Every error message is a conversation with a frustrated user. "An unexpected error occurred" is abandoning that user. "We couldn't send that email. Check the address and try again." is helping them. + +**6. Labels matter.** The name you give a feature shapes how users understand it. "Campfire" (Basecamp's chat feature) evokes warmth and informality. "Team Communication Module" does not. + +**Copy before/after examples:** + +| Before (Generic) | After (37signals Style) | +|------------------|----------------------| +| "Welcome to our platform! Let's get you set up with a seamless onboarding experience." | "Welcome to Basecamp. Let's get your first project started." | +| "An error has occurred. Please contact support." | "That didn't work. Here's what happened and how to fix it:" | +| "Upgrade to our premium tier for enhanced functionality." | "Need more storage? Upgrade for $99/month." | +| "Your notification preferences have been updated successfully." | "Saved." | +| "Leverage our robust integration ecosystem." | "Works with the tools you already use." | + +## Focus on What Won't Change + +Technology trends come and go. User preferences shift. Competitors add and remove features. But some things never change: people want software that is fast, simple, reliable, and respectful of their time. The 37signals bet is to invest disproportionately in these permanent qualities. + +**Permanent qualities worth investing in:** + +- **Speed.** A faster product is always better. This will never change. +- **Simplicity.** Easier to understand is always better. This will never change. +- **Reliability.** Always working is always better. This will never change. +- **Clarity.** Clear communication is always better. This will never change. +- **Respect for user time.** Fewer steps, fewer clicks, fewer distractions. Always better. + +**Transient qualities to be cautious about:** + +- Latest JavaScript framework (will be replaced in 3 years) +- AI features (valuable, but the landscape changes monthly) +- Social features (user expectations shift frequently) +- Integration with trending platforms (platforms rise and fall) + +This does not mean ignoring new technology. It means building on a stable foundation and adopting new technology selectively, when it clearly serves a permanent quality. Use a new framework if it makes the product faster. Do not use it because it is trendy. + +## Out-Teach the Competition + +37signals publishes books, blog posts, conference talks, and free resources about how they work. This is not charity — it is strategy. Teaching your methods openly attracts customers who share your values, establishes authority in your space, and creates a relationship with potential customers long before they buy. + +**What teaching looks like:** + +- **Books.** Getting Real, Rework, Remote, It Doesn't Have to Be Crazy at Work, Shape Up — all share 37signals' methods openly. +- **Blog posts.** Signal v. Noise (now HEY World) publishes opinions about product development, business, and technology regularly. +- **Open source.** Ruby on Rails is the ultimate "sell your by-products" example — a tool built for internal use, released to the world, creating a massive community that feeds back into 37signals' reputation. +- **Transparent practices.** Open salaries, public positions on remote work, published decision frameworks — transparency builds trust. + +**Why teaching works as marketing:** + +- People buy from people they trust. Teaching builds trust. +- Your best customers are people who already agree with your philosophy. Teaching finds them. +- Teaching is durable. A blog post generates leads for years. An ad generates leads for a day. +- Teaching differentiates. Competitors can copy your features. They cannot copy your thinking. + +## Sell Your By-Products + +Every business produces by-products — knowledge, processes, tools, and methods created along the way to the main product. Most companies ignore these. 37signals sells them. + +**37signals by-products:** + +| Main Product | By-Product | Outcome | +|-------------|-----------|---------| +| Basecamp (project management) | Ruby on Rails (web framework) | World's most popular Ruby framework; massive community | +| Building Basecamp | Getting Real, Rework, Shape Up (books) | Millions of copies; established thought leadership | +| Running a remote company | Remote (book) | Influenced the global remote work movement | +| Product development process | Shape Up methodology | Adopted by thousands of companies | +| Building HEY | Blog posts about email philosophy | Generated massive launch buzz | + +**How to identify your by-products:** + +1. What processes did you create that others might find useful? +2. What tools did you build internally that could stand alone? +3. What lessons did you learn that others in your industry would value? +4. What opinions do you hold that are different from the mainstream? + +**How to sell by-products:** + +- Open source internal tools (Rails, Turbo, Stimulus, Hotwire) +- Write about your process (blog posts, books, newsletters) +- Speak about your decisions (conferences, podcasts, interviews) +- Share your templates (pitch templates, hiring processes, team structures) + +By-products are already paid for — the cost of creating them was absorbed by the main product. Selling them is nearly pure upside. diff --git a/.agents/skills/37signals-way/references/shaping-work.md b/.agents/skills/37signals-way/references/shaping-work.md new file mode 100644 index 00000000..629522f9 --- /dev/null +++ b/.agents/skills/37signals-way/references/shaping-work.md @@ -0,0 +1,229 @@ +# Shaping the Work + +## Table of Contents + +- [What Shaping Is](#what-shaping-is) +- [Properties of Shaped Work](#properties-of-shaped-work) +- [Setting the Appetite](#setting-the-appetite) +- [Breadboarding](#breadboarding) +- [Fat Marker Sketches](#fat-marker-sketches) +- [The Pitch Format](#the-pitch-format) +- [Identifying Rabbit Holes](#identifying-rabbit-holes) +- [Defining No-Gos](#defining-no-gos) +- [Who Does the Shaping](#who-does-the-shaping) +- [Shaping in Practice](#shaping-in-practice) + +## What Shaping Is + +Shaping is the work you do before the work. It happens at the intersection of product strategy, design thinking, and technical reality. The goal is to take a raw idea — a customer request, a business opportunity, a nagging problem — and transform it into something a small team can build in a fixed amount of time. + +Shaping is not writing a spec. Specs are too detailed — they remove the team's ability to make creative decisions. Shaping is not writing a user story. User stories are too vague — they leave too many open questions for the team to resolve under time pressure. Shaping sits in between: detailed enough that the main approach is clear, rough enough that the team has room to work out the specifics. + +**What shaping replaces:** + +| Traditional Approach | Problem | Shaping Alternative | +|---------------------|---------|-------------------| +| Detailed specification | Too rigid; team becomes ticket-takers | Shaped pitch with room to maneuver | +| User story ("As a user I want...") | Too vague; team discovers scope problems mid-sprint | Shaped pitch with solution sketched out | +| Wireframes and mockups | Too concrete; invites pixel-level debate too early | Breadboards and fat marker sketches | +| Story point estimation | Focuses on how long, not how much it is worth | Appetite: "This is worth 2 weeks of work" | +| Sprint planning with a backlog | Picks from an ever-growing list of undifferentiated items | Betting table selects from freshly shaped pitches | + +## Properties of Shaped Work + +Shaped work has three essential properties. If any one is missing, the work is not ready to bet on. + +**1. Rough.** The solution is sketched at the right level of abstraction. There are no wireframes, no pixel-level designs, no detailed task lists. The team has room to interpret the solution and make their own design and technical decisions. Roughness is intentional — it signals to the team that they own the details. + +**2. Solved.** Despite being rough, the main elements of the solution are worked out. The shaper has thought through the core flow, identified the key interactions, and resolved the biggest design questions. The team should not have to figure out the fundamental approach — that is the shaper's job. They should figure out the details within that approach. + +**3. Bounded.** The scope is explicitly limited. The appetite sets a time boundary. No-gos set feature boundaries. Rabbit holes are identified and addressed. The team knows what they are building and — just as importantly — what they are not building. + +**How to tell if work is properly shaped:** + +- Can you explain the solution in under 5 minutes using only words and rough sketches? +- Does the solution address the customer's core problem without unnecessary extras? +- Could a small team start building on day one without asking "but what about...?" +- Are the known risks called out and addressed? +- Is it clear what is out of scope? + +If the answer to any of these is no, the work needs more shaping. + +## Setting the Appetite + +The appetite is a time budget that reflects how much the problem is worth. This is fundamentally different from estimation. + +**Estimation asks:** "How long will this take?" The answer depends on the solution, which depends on scope, which depends on what the team discovers, which means the answer is a guess that grows under pressure. + +**Appetite asks:** "How much time is this problem worth to us?" The answer is a strategic decision made before a solution exists. It constrains the solution rather than the solution dictating the timeline. + +**Appetite sizes:** + +| Size | Duration | Team | Typical Use | +|------|----------|------|-------------| +| Small batch | 1-2 weeks | 1-2 people | Bug fixes, small improvements, experiments | +| Large batch | 6 weeks | 2-3 people | New features, significant improvements, redesigns | + +There is no "3-week appetite" or "4-month appetite." The constraint of fixed sizes forces honest classification: either this is small enough for a quick batch, or it is worth a full cycle. If it seems like it is in between, it needs more shaping to fit one size or the other. + +**How appetite changes the conversation:** + +- Without appetite: "How long will the reporting feature take?" "6-8 weeks." "Can you do it in 4?" (negotiation over fiction) +- With appetite: "We think a basic reporting feature is worth a 6-week bet. Can you shape something that solves the core need within that appetite?" (creative problem-solving within constraints) + +## Breadboarding + +A breadboard is an interaction design sketch that uses only words and arrows. No layout, no visual design, no color, no images. Just three elements: + +**Places** — screens, dialogs, or pages the user can navigate to. Written as nouns. + +**Affordances** — things the user can interact with at each place. Written as verbs or interactive elements (buttons, fields, links). + +**Connection lines** — arrows showing how affordances lead to other places. + +**Example breadboard: "User invites a teammate"** + +``` +[Project Settings] + - "Invite" button + ↓ +[Invite Form] + - Email field + - Role selector (Admin / Member) + - "Send Invite" button + ↓ +[Confirmation] + - "Invitation sent to {email}" message + - "Send another" link → [Invite Form] + - "Done" link → [Project Settings] +``` + +**Why breadboards work:** + +- They force you to think about flow before layout +- They are fast to create and easy to change +- They prevent premature conversations about visual design +- They reveal missing steps and edge cases in the interaction +- Anyone can read them — no design tools required + +**When not to use breadboards:** When the challenge is primarily visual (a new data visualization, a complex responsive layout), a fat marker sketch is more appropriate. + +## Fat Marker Sketches + +A fat marker sketch is a visual sketch drawn at low fidelity — as if you were using a thick marker on a whiteboard. The thick line prevents you from drawing details like specific fonts, exact spacing, or precise button sizes. It forces you to think about arrangement and emphasis rather than polish. + +**Rules for fat marker sketches:** + +1. Draw on paper or a tablet with a thick brush — never in a design tool +2. No text labels (or very few) — use blocks and shapes to represent content areas +3. No color — grayscale only +4. No precise alignment — rough positioning is the point +5. Show the most important element prominently; let everything else recede + +**What fat marker sketches communicate:** + +- The relative priority of elements on a page (what is big, what is small) +- The general layout approach (sidebar? stacked? tabbed?) +- Which elements exist and which do not +- The relationship between content areas + +**What they intentionally do not communicate:** + +- Exact spacing, sizing, or alignment +- Typography choices +- Color or visual styling +- Responsive behavior +- Interaction states + +This intentional vagueness is a feature. It gives the building team freedom to design the details while keeping the strategic layout decisions intact. + +## The Pitch Format + +A pitch is the shaped work packaged for the betting table. It is a written document — not a slide deck, not a verbal presentation — because writing forces clarity and allows asynchronous review. + +**Five elements of a pitch:** + +**1. Problem.** What is the problem or opportunity? Describe it from the user's perspective. Include a specific story or scenario that makes the problem concrete. Avoid abstract descriptions. + +**2. Appetite.** How much time is this worth? Small batch (1-2 weeks) or large batch (6 weeks). This is a strategic decision, not a technical estimate. + +**3. Solution.** The shaped solution, presented with breadboards and/or fat marker sketches. Show the core flow and key interactions. Keep it rough — enough to understand the approach, not enough to copy pixel-by-pixel. + +**4. Rabbit holes.** Known risks and complexities that could blow up the scope. For each rabbit hole, explain how the solution addresses it or avoids it. If a rabbit hole cannot be mitigated, it may mean the pitch is not ready. + +**5. No-gos.** Explicit statements about what the solution will not include. These prevent scope creep by making boundaries visible and non-negotiable. "We will not support bulk invitations in this version" is a no-go. + +**Pitch length:** A pitch should take 5-10 minutes to read. If it takes longer, the solution is probably not shaped well enough — it is either too detailed or too complex. + +## Identifying Rabbit Holes + +Rabbit holes are the parts of a project that look simple on the surface but contain hidden complexity that can consume weeks of work. The shaper's job is to identify them before the team encounters them. + +**Common rabbit hole patterns:** + +| Pattern | Example | How to Address | +|---------|---------|---------------| +| Permissions complexity | "Who can see what when a user is shared across projects?" | Simplify the permission model; define only 2 roles for v1 | +| Data migration | "Existing users have data in the old format" | Define a simple migration path or make new feature new-only | +| Edge case explosion | "What if the user has 10,000 items?" | Set a practical limit and document it as a no-go | +| Integration dependency | "This needs the payment provider to support X" | Verify support exists before betting; if not, it is a no-go | +| Performance cliff | "This query will be slow at scale" | Shape the solution to avoid the expensive query (pagination, caching) | + +**How to spot rabbit holes during shaping:** + +1. Walk through the solution step by step and ask "What could go wrong here?" +2. For each interaction, ask "Is there a simpler version that achieves 80% of the value?" +3. Look for words like "just," "simply," or "obviously" in your own thinking — they often mask complexity +4. Ask an engineer to review the pitch for technical rabbit holes +5. Ask a designer to review for interaction rabbit holes + +## Defining No-Gos + +No-gos are explicit boundaries that prevent scope creep during the build. They state what the solution will not include, even if those exclusions seem like obvious additions. + +**Why no-gos matter:** + +- They prevent the building team from expanding scope based on their own good judgment +- They make trade-offs visible to the betting table +- They give teams permission to not build something without feeling like they are cutting corners +- They make the appetite honest — the solution fits the time budget because these things are excluded + +**Good no-go examples:** + +- "No bulk operations in v1 — users invite one person at a time" +- "No custom notification schedules — we pick a sensible default" +- "No mobile-responsive version for this feature — desktop only" +- "No CSV import — users enter data manually or use the API" +- "No undo — actions are confirmed before execution" + +**Bad no-go examples (too vague):** + +- "No over-engineering" +- "Keep it simple" +- "Don't spend too much time on edge cases" + +No-gos must be specific and concrete. A team member should be able to look at a no-go and immediately know whether their current work violates it. + +## Who Does the Shaping + +Shaping is a senior role. The shaper needs to understand the business context (which problems are worth solving), the user perspective (what workflows look like), and the technical landscape (what is easy and what is hard to build). This rare combination usually means shaping is done by a founder, a senior product person, or a senior designer who is technically fluent. + +**Shaping is not a committee activity.** One or two people shape a pitch. They may consult others — an engineer for technical feasibility, a support person for common complaints — but the shaping itself is done by a small number of people who can hold the whole picture in their head. + +**Shaping is not the building team's job.** If the team doing the building also does the shaping, they end up shaping during the build, which defeats the purpose. The building team's job is to take a shaped pitch and figure out the implementation details. The shaper's job is to make sure the pitch is ready for that. + +## Shaping in Practice + +**Step 1: Set the appetite.** Before exploring solutions, decide how much time the problem is worth. This prevents the shaper from accidentally designing a 3-month solution for a 2-week problem. + +**Step 2: Narrow the problem.** Move from a broad problem ("reporting is bad") to a specific scenario ("managers need to know which projects are behind schedule this week"). The narrower the problem, the easier it is to shape a bounded solution. + +**Step 3: Sketch the solution.** Use breadboards for flow-heavy problems and fat marker sketches for layout-heavy problems. Work quickly — if the sketch takes more than 30 minutes, the problem might need more narrowing. + +**Step 4: Identify rabbit holes.** Walk through the solution and flag anything that could blow up. Address each one: simplify, exclude, or find a workaround. + +**Step 5: Define no-gos.** Write down what the solution will not include. Be specific. + +**Step 6: Write the pitch.** Package everything into the five-element pitch format. Share it for review before bringing it to the betting table. + +**Time investment:** Shaping a single pitch typically takes 1-3 days of focused work, spread over a week or two. This is a fraction of the time the building team will spend, but it dramatically reduces the risk of building the wrong thing. diff --git a/.agents/skills/37signals-way/references/small-teams-execution.md b/.agents/skills/37signals-way/references/small-teams-execution.md new file mode 100644 index 00000000..762df35c --- /dev/null +++ b/.agents/skills/37signals-way/references/small-teams-execution.md @@ -0,0 +1,216 @@ +# Small Teams and Execution + +## Table of Contents + +- [The Three-Person Team](#the-three-person-team) +- [Team Autonomy](#team-autonomy) +- [Discovering Scopes](#discovering-scopes) +- [Hill Charts](#hill-charts) +- [Getting Real](#getting-real) +- [Async Communication](#async-communication) +- [Launch Now, Iterate Later](#launch-now-iterate-later) +- [Integrating Design and Programming](#integrating-design-and-programming) + +## The Three-Person Team + +The fundamental unit of work at 37signals is a team of three: one designer and two programmers, or one designer and one programmer for smaller bets. No project manager. No dedicated QA person. No scrum master. Three people who build the entire thing together. + +**Why three:** + +- **Communication overhead scales quadratically.** With 3 people, there are 3 communication paths. With 6 people, there are 15. With 10, there are 45. Small teams communicate naturally — in conversations, not meetings. +- **Shared context comes automatically.** Three people working on the same shaped pitch can hold the entire project in their heads. They do not need status documents to stay aligned. +- **Accountability is clear.** When three people own a bet, there is nowhere to hide. Everyone contributes, everyone is responsible. +- **Decision-making is fast.** Three people can make a decision in a five-minute conversation. Ten people need a meeting with an agenda and follow-up action items. + +**What the three-person team does not have:** + +| Role | Why It Is Absent | What Replaces It | +|------|-----------------|-----------------| +| Project manager | Shaped pitches eliminate ambiguity; small teams self-organize | The team manages itself using hill charts | +| Product manager (during the cycle) | Shaping happens before the cycle; the PM shapes, not manages | The shaper hands off the pitch; the team builds | +| QA engineer | Three people test as they build; scope is small enough to verify | Integrated testing by the building team | +| Scrum master | No sprints, no ceremonies, no process to facilitate | No process overhead — the team just builds | +| Tech lead (separate from the team) | The senior programmer on the team makes technical decisions | Technical leadership comes from within the team | + +**What happens when a bet needs more than three people:** It does not get more people. It gets re-shaped. If a shaped pitch requires more than three people, the pitch is too big or too vague. Break it into smaller, independent bets that each fit a three-person team. + +## Team Autonomy + +Once a team receives a shaped pitch and the cycle begins, they are autonomous. No one assigns them tasks, checks their progress daily, or tells them how to build. They own the entire bet from start to finish. + +**What autonomy means in practice:** + +- The team decides the technical approach (which frameworks, which database schema, which architecture) +- The team decides the design details (layout, typography, interaction patterns) +- The team decides the build order (which scopes to tackle first, which to defer) +- The team decides when to cut scope (within the boundaries of the pitch's no-gos) +- The team decides when to ship (within the six-week constraint) + +**What autonomy does not mean:** + +- Ignoring the shaped pitch — the pitch defines the boundaries; the team fills in the details +- Skipping communication — the team posts hill chart updates and writes up decisions for transparency +- Expanding scope — autonomy is freedom within constraints, not freedom to redefine the bet +- Working in isolation — team members collaborate closely with each other; they just do not need external direction + +**Why autonomy works:** When people own their work, they bring better judgment, more energy, and more creativity than when they are executing someone else's task list. Autonomy also attracts and retains talented people who want to do meaningful work, not follow instructions. + +## Discovering Scopes + +When a team receives a shaped pitch, their first job is to discover scopes — named chunks of work that can be built and tracked somewhat independently. Scopes are not pre-defined; the team discovers them by exploring the pitch. + +**What a scope is:** + +- A meaningful piece of the project that can move through the hill independently +- Named with a descriptive label (e.g., "User Invitations," "Permission Checks," "Email Notifications") +- Big enough to be meaningful (not a single task) but small enough to complete in days, not weeks +- Defined by the team based on their understanding of the work, not by the shaper + +**How to discover scopes:** + +1. **Read the pitch thoroughly.** Understand the problem, the solution, the rabbit holes, and the no-gos. +2. **Start building.** Do not spend days planning — start with the most uncertain part of the project. +3. **Notice natural boundaries.** As you work, pieces of the project naturally group together. A set of related database changes, a UI component, an integration point — these become scopes. +4. **Name them.** Give each scope a clear, descriptive name. The name should communicate what the scope is about to someone who has not read the code. +5. **Revise as you learn.** Scopes evolve during the cycle. Some merge, some split, some turn out to be unnecessary. This is normal and expected. + +**Scopes vs. tasks:** + +| Scopes | Tasks | +|--------|-------| +| Named by the team based on discovered structure | Assigned by a PM or tech lead based on a spec | +| Group related work together | Individual work items | +| Track on a hill chart (figuring out → done) | Track in a list (to-do → done) | +| Evolve during the cycle | Fixed at sprint planning | +| Communicate what area is progressing | Communicate whether a checklist item is ticked | + +## Hill Charts + +Hill charts are the 37signals alternative to burndown charts, percentage-complete metrics, and status meetings. A hill chart shows each scope as a dot on a hill. The left side of the hill is "uphill" (figuring things out), and the right side is "downhill" (executing known work). + +**The shape of the hill:** + +``` + · ← summit (figured out, ready to execute) + / \ + / \ +uphill / \ downhill + / \ + / \ +____/ \____ +figuring out executing +(uncertainty) (certainty) +``` + +**How to read a hill chart:** + +- **Dot on the far left:** The team has not started this scope yet. +- **Dot climbing uphill:** The team is exploring, figuring out the approach, encountering unknowns. +- **Dot near the summit:** The core approach is figured out but implementation has not started. +- **Dot going downhill:** The approach is clear and the team is executing — this is the "boring" productive work. +- **Dot at the far right:** The scope is done. + +**Why hill charts work better than other progress tracking:** + +| Method | Problem | Hill Chart Advantage | +|--------|---------|---------------------| +| Percentage complete | "80% done" can mean "80% of tasks done but the hard 20% remains" | Shows whether uncertainty is resolved or not | +| Burndown chart | Treats all tasks as equal; does not distinguish exploration from execution | Uphill/downhill distinction reveals where the real risk is | +| Status meeting | "It's going well" hides problems until it is too late | A dot stuck uphill for two weeks is a visible red flag | +| Task list | Checked boxes feel like progress even if the hardest work is untouched | Scopes stuck uphill force honest conversation about risk | + +**Using hill charts to manage risk:** + +The most important thing a hill chart reveals is which scopes are stuck uphill. A scope that has been uphill for more than two weeks is a warning sign — the team is struggling with uncertainty. This triggers a conversation: Is the scope too big? Is there a rabbit hole that was not identified during shaping? Does the scope need to be re-shaped or cut? + +**How often to update hill charts:** At least twice per week. Updates should take less than two minutes — just drag the dots to their current position. No written status reports needed. + +## Getting Real + +"Getting real" is the 37signals principle of working with real materials as early as possible. In software, real materials are HTML, CSS, JavaScript, and real data — not wireframes, not prototypes, not mockups with lorem ipsum. + +**What "getting real" looks like:** + +- Build the actual interface in the browser on day one or two, not in a design tool +- Use real data (or realistic fake data), not "lorem ipsum" and placeholder content +- Make it functional as fast as possible, even if it is ugly — then improve the design +- Test with real interactions (clicking, typing, navigating), not static screenshots + +**Why getting real works:** + +- **You discover problems earlier.** Wireframes and mockups hide interaction problems that become obvious when you click through real HTML. +- **You make better design decisions.** Seeing real content in a real browser reveals what works and what does not in a way that static images cannot. +- **You avoid the handoff problem.** When designers work in Figma and engineers implement separately, translation losses are inevitable. When the designer and programmer build together in the browser, the output is the real thing. +- **You ship faster.** The prototype becomes the product. There is no throwaway work. + +**Getting real does not mean skipping design:** It means the design happens in the medium of the final product (HTML/CSS) rather than in an intermediate medium (Figma/Sketch). The designer and programmer collaborate in the browser from day one. + +## Async Communication + +Meetings are toxic at 37signals. Not because meetings are always bad, but because they are almost always overused. A one-hour meeting with six people is not a one-hour meeting — it is six hours of collective time. And most of that time is wasted by the majority who are listening rather than contributing. + +**The async-first approach:** + +- **Write it up.** If you have something to share, write a message, a document, or a post. People can read it on their own schedule and respond thoughtfully. +- **Record a Loom.** If you need to show something visual, record a 5-minute video walkthrough. It is faster to make than a meeting is to schedule, and everyone can watch at 2x speed. +- **Use hill chart updates.** The hill chart replaces the daily standup. Anyone can see where the project stands by looking at the chart. +- **Reserve meetings for conversations.** Meetings are appropriate when you need real-time back-and-forth to resolve a disagreement or brainstorm. They are not appropriate for status updates, announcements, or information sharing. + +**The 37signals communication hierarchy:** + +| Need | Method | Why | +|------|--------|-----| +| Status update | Hill chart + async post | No meeting needed; people check on their own time | +| Decision announcement | Written post | Documentation is built-in; everyone gets the same information | +| Design feedback | Loom video + written comments | Async review is more thoughtful than real-time critique | +| Complex problem-solving | Real-time conversation (2-3 people) | Keep it small, keep it focused, keep it short | +| Team alignment | Written pitch or kickoff post | The shaped pitch IS the alignment document | + +## Launch Now, Iterate Later + +The 37signals philosophy strongly favors shipping over perfecting. Working software in the hands of real users generates more useful feedback in one day than months of internal review. + +**What "launch now" means:** + +- Ship at the end of the six-week cycle, even if some nice-to-have scopes were cut +- Ship to real users, not to a staging environment for internal review +- Accept that the first version will not be perfect — it should be good, but not perfect +- Plan to iterate in future cycles based on real usage data, not hypothetical feedback + +**What "launch now" does not mean:** + +- Ship broken software — everything that ships should work correctly +- Skip testing — the building team tests as they build +- Ignore quality — the shipped version should be polished within its reduced scope +- Never improve — iteration is expected; "launch now" is the beginning, not the end + +**The iteration cycle:** + +1. Ship the first version (end of six-week cycle) +2. Observe real usage during the cool-down period +3. If improvements are needed, shape a follow-up pitch +4. Bring the follow-up pitch to the next betting table +5. If it wins the bet, build the improvement in the next cycle + +## Integrating Design and Programming + +Traditional product development separates design and engineering into sequential phases: design first, then build. The 37signals approach integrates them from day one. The designer and programmer(s) work together on the same scopes simultaneously. + +**How integration works in practice:** + +- **Day 1-2:** The designer starts building real HTML/CSS for the core interaction. The programmer sets up the data model and backend. They sync frequently. +- **Day 3-5:** The designer refines the interface while the programmer connects it to real data. They work on the same scope, in the same codebase. +- **Week 2+:** Design and engineering decisions are made together, in context. "Should this be a modal or a page?" is answered by building both and seeing which one works. + +**Why integration matters:** + +- No handoff problems — the designer sees the real implementation, not a screenshot +- Faster decision-making — questions are resolved in minutes, not in a review meeting next week +- Better solutions — the designer understands technical constraints; the programmer understands design intent +- Single source of truth — the codebase is the design, not a Figma file that may be out of date + +**What this requires from the team:** + +- Designers must be comfortable working with HTML/CSS or closely pairing with a programmer +- Programmers must care about the user experience, not just the code +- Both must be willing to change their work based on what they learn together diff --git a/.agents/skills/37signals-way/references/ux-ui-copy.md b/.agents/skills/37signals-way/references/ux-ui-copy.md new file mode 100644 index 00000000..adbdf78c --- /dev/null +++ b/.agents/skills/37signals-way/references/ux-ui-copy.md @@ -0,0 +1,264 @@ +# The 37signals Approach to UX, UI, and Copy + +## Table of Contents + +- [Design Philosophy](#design-philosophy) +- [UX Principles](#ux-principles) +- [UI Design Approach](#ui-design-approach) +- [Copywriting as Product Design](#copywriting-as-product-design) +- [The Basecamp Design Process](#the-basecamp-design-process) +- [Interface Patterns](#interface-patterns) +- [Writing the Interface](#writing-the-interface) +- [Anti-Patterns](#anti-patterns) + +## Design Philosophy + +The 37signals design philosophy rests on a single conviction: design is not decoration. Design is how it works. Every pixel, every word, every interaction is a product decision. The goal is not to make software that looks beautiful in a screenshot — it is to make software that feels obvious in use. + +This means design starts with the problem, not the screen. Before asking "What should this look like?", ask "What is the user trying to do, and what is the fastest path to doing it?" The answer shapes everything: the layout, the copy, the interactions, and — critically — what is not on the screen. + +**The three design principles:** + +1. **Clarity over cleverness.** A clever interface that confuses users is a failed interface. A boring interface that gets the job done is a successful one. +2. **Reduction over addition.** When a screen is not working, the first instinct should be to remove elements, not add them. Most design problems are caused by too much, not too little. +3. **Convention over innovation.** Use standard patterns (links look like links, buttons look like buttons, forms work like forms) unless there is a compelling reason not to. Innovation for its own sake is a cost, not a benefit. + +## UX Principles + +### Start with the Core Job + +Every screen in the product should serve a clear purpose connected to the user's core job. If you cannot articulate what the user is trying to accomplish on a screen, the screen should not exist. + +**The one-screen test:** Can you describe what the user does on this screen in one sentence? If you need two sentences, the screen is doing too much. Split it or simplify it. + +**Examples:** +- "The user sees all their projects and opens one." (Projects list — clear purpose) +- "The user writes a message to their team." (Message composer — clear purpose) +- "The user sees their dashboard with activity feed, upcoming deadlines, team status, notifications, and quick actions." (Dashboard — doing too much; simplify) + +### Reduce to the Essence + +For every element on the screen, ask: "If I remove this, does the user fail at their task?" If the answer is no, remove it. Start with the minimum viable screen and add only what is proven necessary. + +**The removal checklist:** + +| Element | Keep If | Remove If | +|---------|---------|-----------| +| Navigation item | User needs it at least weekly | It serves < 10% of users or is accessible from another path | +| Form field | Data is required to complete the task | Data is "nice to have" or can be inferred | +| Confirmation dialog | Action is destructive and irreversible | Action is easily undone | +| Tooltip or help text | The UI element is genuinely confusing | Better solution: rename the element so it is self-explanatory | +| Loading indicator | Operation takes > 1 second | Operation is instant | +| Success notification | User needs confirmation to proceed | The result of the action is already visible on screen | + +### Design for the Happy Path First + +Design the screen for the most common scenario first. Get that working perfectly. Then handle edge cases, empty states, and error states. Most users will experience the happy path most of the time — invest your design energy proportionally. + +**Priority order for design attention:** +1. The happy path (80% of user time) +2. Empty states (first-time experience) +3. Error states (things that go wrong) +4. Edge cases (unusual but valid scenarios) +5. Power user features (requested by few, used by fewer) + +### Make Navigation Obvious + +Users should always know where they are, how they got there, and how to get back. This sounds basic because it is — and yet most software fails at it. The 37signals approach: use clear breadcrumbs, descriptive page titles, and consistent navigation patterns. Never make the user guess where they are. + +## UI Design Approach + +### Build in the Browser + +The 37signals approach to UI design is to build in the browser from day one. This means HTML and CSS, not Figma or Sketch. The browser is the final medium — designing in an intermediate tool and then translating is waste. + +**Why browser-first design works:** + +- **Real interactions.** You can click, scroll, and type. You discover interaction problems immediately. +- **Real constraints.** Browser rendering, responsive behavior, and performance are immediate. No surprises at implementation time. +- **Real content.** Using real data instead of lorem ipsum reveals length issues, truncation needs, and content hierarchy problems. +- **No handoff.** The "design" and the "implementation" are the same artifact. Nothing is lost in translation. + +**What this does not mean:** It does not mean the designer must write production-quality code. It means the designer works in HTML/CSS (possibly with a programmer pairing) to create the real interface. The code may be rough — it gets refined during the cycle. + +### Visual Hierarchy Through Weight, Not Decoration + +The 37signals UI style relies on content hierarchy achieved through font weight, size, color contrast, and whitespace — not through borders, backgrounds, shadows, or decorative elements. + +**Hierarchy tools (in order of preference):** + +1. **Font size.** Bigger = more important. Simple and universal. +2. **Font weight.** Bold = emphasis. Use sparingly — if everything is bold, nothing is. +3. **Color contrast.** High contrast (black text) = primary. Low contrast (gray text) = secondary. One accent color for interactive elements. +4. **Whitespace.** Generous spacing groups related elements and separates unrelated ones. Whitespace is not empty space — it is a design element. +5. **Position.** Top-left is where the eye goes first (in LTR languages). Put the most important thing there. + +**What to avoid:** + +- Excessive borders and dividers — use whitespace to separate instead +- Background colors on every section — reserve background color for meaningful distinction +- Shadow on every card — use shadow sparingly to create meaningful depth +- Icon overuse — icons without labels are ambiguous; use text labels + +### Responsive as Reduction + +When designing for smaller screens, the 37signals approach is not "rearrange everything to fit" but "remove what is not essential at this size." A mobile interface is not a shrunk desktop interface — it is a simpler interface that serves the most common mobile use cases. + +**Mobile reduction principles:** + +- Show only the primary action, not all available actions +- Use full-screen flows instead of modals or sidebars +- Reduce navigation to essential items only +- Prioritize reading and quick actions over complex editing +- Accept that some features are desktop-only — that is okay + +### Use Standard Components + +Do not invent custom UI components when standard ones exist. A standard dropdown, a standard checkbox, a standard text input — users already know how these work. Custom components carry a learning cost. + +**When custom components are justified:** +- The standard component genuinely cannot serve the use case (rare) +- The custom component is dramatically simpler than the standard alternative +- The custom component is used repeatedly throughout the product (worth the investment) + +**When custom components are not justified:** +- "It looks cooler" — users do not care about cool; they care about familiar +- "It matches our brand" — brand is expressed through content and tone, not through reinventing checkboxes +- "The designer wanted it" — design serves users, not designers' portfolios + +## Copywriting as Product Design + +At 37signals, interface copy is not an afterthought — it is a core design element. The words on the screen shape user expectations, guide behavior, and build (or erode) trust. Copy is written by the people who design and build the product, not by a separate copywriting team. + +### The Copy Rules + +**1. Use the fewest words possible.** Every word on the screen competes for the user's attention. Remove words that do not earn their place. + +| Wordy | Concise | +|-------|---------| +| "Click the button below to save your changes" | "Save" (button label) | +| "Are you sure you want to delete this item? This action cannot be undone." | "Delete this? It can't be undone." | +| "You have successfully completed the setup process." | "You're all set." | +| "In order to proceed, please enter your email address in the field below." | "Email" (field label) | + +**2. Use the simplest words possible.** Write at a 6th-grade reading level. Not because users are unsophisticated, but because simple words are processed faster by everyone, including experts. + +| Complex | Simple | +|---------|--------| +| "Utilize" | "Use" | +| "Terminate" | "End" | +| "Configure" | "Set up" | +| "Authenticate" | "Sign in" | +| "Facilitate" | "Help" | +| "Leverage" | "Use" | + +**3. Be specific, not abstract.** Tell the user exactly what will happen, not what category of thing will happen. + +| Abstract | Specific | +|----------|---------| +| "Manage your account" | "Change your name, email, or password" | +| "Enhanced collaboration features" | "Invite your team and share files" | +| "Optimize your workflow" | "Send automatic reminders when tasks are due" | + +**4. Write how you talk.** Read your copy aloud. If it sounds robotic or stilted, rewrite it. Interface copy should sound like a helpful colleague, not a legal document. + +**5. Be honest about what is happening.** If something will take time, say so. If there are limitations, disclose them. If something went wrong, explain what happened. Never use vague language to hide bad news. + +### Error Messages as Conversations + +Error messages are the most neglected and most important copy in any application. A user encountering an error is frustrated — the error message is your chance to help them or abandon them. + +**The error message formula:** + +1. **What happened** (in plain language) +2. **Why it happened** (if the user can understand the cause) +3. **What to do next** (specific action the user can take) + +**Examples:** + +| Bad | Good | +|-----|------| +| "Error 422: Unprocessable Entity" | "That email address is already in use. Try signing in instead?" | +| "An unexpected error occurred" | "Something went wrong on our end. Try again in a few minutes." | +| "Invalid input" | "Names can only contain letters and spaces." | +| "Request failed" | "We couldn't reach the server. Check your connection and try again." | + +### Empty States as Onboarding + +An empty state (a screen with no content yet) is not an error — it is an opportunity. It is the user's first encounter with a feature, and it should teach them what to do next. + +**Good empty state pattern:** + +1. A brief explanation of what this area is for (one sentence) +2. A clear call to action (one button or link) +3. Optionally, a short example of what the area looks like when populated + +**Example:** +- Bad empty state: "No items found." +- Good empty state: "This is where your team's messages live. Post the first one?" [New Message button] + +## The Basecamp Design Process + +The design process at 37signals integrates design thinking into every phase of the Shape Up cycle. + +**During shaping (before the cycle):** + +- The shaper uses breadboards to map the core interaction flow +- Fat marker sketches establish the general layout approach +- Copy is drafted for key screens — labels, button text, primary messages +- No pixel-level design work happens yet + +**During building (the cycle):** + +- **Days 1-3:** The designer builds the core screen in HTML/CSS with real (or realistic) copy. The programmer connects it to data. The interface is ugly but functional. +- **Days 4-10:** Design and code evolve together. The designer refines layout, typography, and spacing while the programmer implements functionality. They work on the same scopes. +- **Weeks 3-5:** The interface takes its final shape. Copy is refined. Edge cases are designed as they are discovered. Scope decisions happen in real time. +- **Week 6:** Polish. The team reviews every screen for consistency, clarity, and quality. Final copy review. Final visual review. + +**Design decisions are made in context:** The designer does not design all screens up front and hand them off. They design each scope as it is built, making decisions with the full context of real data, real interactions, and real constraints. + +## Interface Patterns + +### Progressive Disclosure + +Show the minimum necessary information first. Reveal more detail on demand. This keeps screens clean while still providing depth for users who need it. + +**Examples:** +- Show a list of tasks. Click a task to see its details, comments, and history. +- Show a project summary. Expand sections to see individual metrics. +- Show the primary form fields. Link to "Advanced options" for rarely-used settings. + +### Confirmation Through Visibility + +Instead of showing a success toast or modal ("Item saved!"), make the result of the action visible in the interface itself. The user sees the item appear in the list, the status change, the content update. The interface is its own confirmation. + +**When explicit confirmation is needed:** +- Destructive actions (delete, cancel, remove) +- Actions with delayed effects (email sent, payment processed) +- Actions where the result is not immediately visible on the current screen + +### One Primary Action per Screen + +Every screen should have one primary action — the thing the user is most likely to do. Make it visually prominent. Secondary actions can exist but should be visually subordinate. + +**How to implement:** +- One button with the primary style (colored, prominent) +- Secondary actions as text links or muted buttons +- Destructive actions in a separate area or behind a menu + +## Anti-Patterns + +These are common UI/UX patterns that violate the 37signals approach: + +| Anti-Pattern | Why It Fails | 37signals Alternative | +|-------------|-------------|---------------------| +| Dashboard with 12 widgets | Overwhelms; users ignore most of it | Show one thing well; link to details | +| Wizard with 7 steps | Too much friction for setup | Ask the minimum; infer the rest | +| Modal upon modal | Creates navigation confusion | Use full pages for complex interactions | +| Tooltip on every element | Signals that the UI is not self-explanatory | Rename elements to be clear without help | +| "Are you sure?" for everything | Creates modal fatigue; users click through without reading | Only confirm destructive, irreversible actions | +| Custom scrollbars | Breaks platform conventions; accessibility risk | Use native scrollbars | +| Infinite configuration page | Pushes decisions to users who do not want to make them | Pick defaults; reduce options | +| Feature comparison table on pricing | Overwhelms with complexity; induces analysis paralysis | Simple plan descriptions focusing on the job each plan serves | +| Auto-playing animations | Distracts from content; accessibility concern | Static by default; animate only on interaction | +| Notification badges on everything | Creates anxiety; trains users to ignore notifications | Notify only for things that require action | diff --git a/.agents/skills/blue-ocean-strategy/SKILL.md b/.agents/skills/blue-ocean-strategy/SKILL.md new file mode 100644 index 00000000..2486dc92 --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/SKILL.md @@ -0,0 +1,171 @@ +--- +name: blue-ocean-strategy +description: 'Create uncontested market space using value innovation instead of competing head-to-head. Use when the user mentions "blue ocean", "red ocean", "strategy canvas", "ERRC framework", "value innovation", "non-customers", "buyer utility map", "the market is too crowded", "how do we stand out", or "escape the price war". Also trigger when exploring a new market category, or finding underserved or non-customers. Covers the Four Actions Framework, Six Paths, buyer utility map, and value-cost trade-offs. For real strategy formulation and bad-strategy detection, see good-strategy-bad-strategy. For tech adoption strategy, see crossing-the-chasm. For product positioning, see obviously-awesome.' +license: MIT +metadata: + author: wondelai + version: "1.4.1" +--- + +# Blue Ocean Strategy Framework + +Strategic framework for creating uncontested market space that makes the competition irrelevant, based on the simultaneous pursuit of differentiation and low cost. + +## Core Principle + +**Don't compete in bloody red oceans. Create blue oceans of uncontested market space.** Most companies fight for share in existing industries; winners create new market space where competition is irrelevant by delivering a leap in value for both buyers and themselves. Competition-based strategy is zero-sum — value innovation creates new demand and breaks the value-cost trade-off. + +## Scoring + +**Goal: 10/10.** Score a strategy by how many of the five Quick Diagnostic rows it satisfies, mapped to the bands below: + +- **9-10** — divergent strategy-canvas curve, eliminates AND creates factors, breaks the value-cost trade-off, converts non-customers, and delivers a 10x utility leap (all 5 rows). +- **7-8** — value innovation is real but one gate is weak (e.g. strong divergence and cost cuts, but still chasing existing customers rather than non-customers). +- **5-6** — differentiation without cost cuts, or cost cuts without a value leap: better than rivals on the same factors, not yet value innovation (2-3 rows). +- **<=3** — competes on the same factors as rivals with a look-alike canvas curve: a red ocean (0-1 rows). + +Report the current score, which diagnostic rows fail, and the specific ERRC/Six-Paths moves needed to reach 10/10. + +## Framework + +### 1. Red Ocean vs. Blue Ocean + +**Core concept:** Red oceans are existing market spaces where rivals fight over shrinking profits; blue oceans are new market spaces where the competition is irrelevant. + +| Red Ocean Strategy | Blue Ocean Strategy | +|-------------------|---------------------| +| Compete in existing market space | Create uncontested market space | +| Beat the competition | Make competition irrelevant | +| Exploit existing demand | Create and capture new demand | +| Make the value-cost trade-off | Break the value-cost trade-off | +| Align with differentiation OR low cost | Pursue differentiation AND low cost | + +**Examples:** Airlines competing on routes, amenities, and price are red ocean; Cirque du Soleil inventing a new entertainment form, Netflix replacing rental with streaming, and Nintendo Wii trading graphics power for accessible motion gaming are blue. + +See [references/blue-ocean-examples.md](references/blue-ocean-examples.md) when you want a full worked case to model a move on — Cirque du Soleil, Netflix, Yellow Tail, and Nintendo Wii broken down factor by factor. + +### 2. Value Innovation + +**Core concept:** The cornerstone of blue ocean strategy — pursue differentiation and low cost simultaneously, creating a leap in value for buyers and the company. Eliminating and reducing over-served factors cuts cost at the same time raising and creating factors lifts buyer value, so value rises faster than cost and the trade-off competitors assume is fixed breaks. + +| Traditional View | Value Innovation View | +|-----------------|---------------------| +| High value = high cost | High value CAN = low cost | +| Differentiate OR cut costs | Differentiate AND cut costs | +| Better performance on established factors | New factors; eliminate old factors | + +**Example — Cirque du Soleil:** eliminated animal shows, star performers, multiple arenas (cost down); reduced thrill and humor; raised venue quality, artistic music and dance; created theme, refined environment, multiple productions. Outcome: priced above circus, costs below theater, a new market. + +See [references/value-innovation.md](references/value-innovation.md) when testing whether an idea is genuine value innovation — the Utility x Price x Cost formula with all three terms and the test questions for each. + +### 3. Strategy Canvas + +**Core concept:** The diagnostic tool — plot the factors an industry competes on against the offering level for you and competitors. Red oceans show everyone's curve looking the same; a divergent curve signals a blue ocean. + +**How to use:** +1. List the industry's competing factors (wine: price, prestige, aging quality, vineyard legacy, complexity, range, marketing) +2. Plot your curve and competitors' — expect near-identical curves in a red ocean +3. Ask: which factors do buyers not actually care about? What could be eliminated, reduced, raised, or created? Where does the buyer experience hurt? + +**Example — Yellow Tail wine:** + +| Factor | Industry Average | Yellow Tail | +|--------|-----------------|-------------| +| Price, prestige, aging quality | Medium-High | LOW | +| Vineyard legacy, complexity, range | High | LOW | +| Easy drinking | Low | HIGH | +| Fun/adventure, accessibility | Low | HIGH | + +**Result:** A different curve = blue ocean. + +See [references/strategy-canvas.md](references/strategy-canvas.md) when plotting your own canvas — a blank template and step-by-step build instructions. + +### 4. Four Actions Framework (ERRC Grid) + +**Core concept:** Four questions that reconstruct buyer value — Eliminate and Reduce cut costs; Raise and Create lift value. + +| Action | Question | Examples | Effect | +|--------|----------|----------|--------| +| **Eliminate** | Which taken-for-granted factors add no buyer value? | Cirque: animals, stars; Southwest: meals, seat assignments; IKEA: sales staff, assembly | Cost down; friction removed | +| **Reduce** | What can go well below industry standard? | Yellow Tail: prestige, complexity; Salesforce v1: customization | Cost down; over-serving stops | +| **Raise** | What should go well above industry standard? | Cirque: artistic value; Dyson: suction, design; Apple: UX | Value up; hard to match | +| **Create** | What has the industry never offered? | Netflix: unlimited streaming, no late fees; Uber: live tracking, cashless payment | New demand; attracts non-customers | + +**Ethical boundary:** Don't eliminate factors buyers truly value (especially safety or accessibility) — test assumptions before cutting. + +See [references/errc-grid.md](references/errc-grid.md) when running the exercise with a team — a 3.5-hour workshop format, validation checklists, and fresh ERRC matrices for Zoom, IKEA, MinuteClinic, and Khan Academy. + +### 5. Six Paths Framework + +**Core concept:** Six systematic ways to look beyond existing industry boundaries and spot blue ocean opportunities. + +| Path | Look across | Example | How to apply | +|------|-------------|---------|--------------| +| **1. Alternative industries** | Different forms solving the same need | NetJets: alternative to both airlines and jet ownership | Map alternatives → find unmet needs across them | +| **2. Strategic groups** | Clusters pursuing similar strategies | Lexus: luxury at accessible price | Find over/under-served needs → position between groups | +| **3. Chain of buyers** | Purchasers vs. users vs. influencers | Novo Nordisk insulin pens: shifted focus from doctors to patients; Bloomberg: traders, not IT purchasers | Identify every buyer in the chain → serve the overlooked one | +| **4. Complementary offerings** | What happens before, during, after use | Babysitting complements movies → "date night" packages | Map the total experience → bundle away pain points | +| **5. Functional ↔ emotional appeal** | Flip the industry's basis of appeal | Swatch: watches as fashion; The Body Shop: cosmetics as ethics | Identify current appeal → build the hybrid | +| **6. Time** | Irreversible trends | iPod/iTunes anticipating digital music; Tesla on EVs | Project the trend's endpoint → build for it today | + +See [references/six-paths.md](references/six-paths.md) when hunting for opportunities path by path — the prompting questions and a worked example for each of the six. + +### 6. Three Tiers of Non-Customers + +**Core concept:** Blue oceans are created by converting non-customers, not by stealing competitors' customers — non-customers reveal the demand the industry is leaving on the table. + +| Tier | Who they are | Opportunity | Example | +|------|--------------|-------------|---------| +| **1. Soon-to-be** | Edge of your market, minimally using, ready to jump ship | Small shifts win them over | Pret A Manger: professionals who wanted fast AND healthy | +| **2. Refusing** | Considered the industry and consciously rejected it | Remove the barrier behind the refusal | JCDecaux: cities refused outdoor ads until bus shelters came free | +| **3. Unexplored** | Distant markets that never considered you an option | Reframe the offering for their needs | Callaway Big Bertha: beginners and occasional golfers | + +**Process:** map all three tiers → find commonalities across tiers → identify what would unlock massive demand → build the offering to convert them. + +See [references/non-customers.md](references/non-customers.md) when sizing latent demand — how to map each of the three tiers and find the commonalities that unlock them. + +### 7. Strategic Sequence: Utility → Price → Cost → Adoption + +**Core concept:** Validate a blue ocean idea in strict order — exceptional buyer utility first, then accessible price, then profitable cost, then adoption hurdles. Failing any gate means rework before proceeding. + +| Step | Question | How | +|------|----------|-----| +| **1. Buyer utility** | Is there exceptional utility? | Check six levers (productivity, simplicity, convenience, risk reduction, fun/image, environmental friendliness) across the buyer experience cycle (purchase → delivery → use → supplements → maintenance → disposal); solve the biggest blocks | +| **2. Strategic price** | Is it accessible to the mass of buyers? | Price against alternatives in other forms, not your costs or direct competitors — Cirque priced above circus, below theater | +| **3. Target cost** | Can we profit at that price? | Strategic price − target margin = target cost; hit it via ERRC and partnering — never by sacrificing utility, never "later" | +| **4. Adoption** | Who will resist — employees, partners, public, regulators? | Surface hurdles upfront: educate stakeholders, run pilots, engage partners early | + +**Ethical boundary:** Win adoption by genuinely addressing stakeholder concerns, not by steamrolling the employees and partners who bear the costs of the shift. + +See [references/sequence.md](references/sequence.md) when validating an idea gate by gate — the buyer-utility map, strategic-pricing corridor, and target-costing worksheet. See [references/implementation.md](references/implementation.md) when moving from idea to rollout — overcoming the four organizational hurdles and aligning the team behind the shift. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|------| +| **Competing on the same factors** | Stuck in the red ocean | Use ERRC to eliminate and create factors | +| **Differentiation without cost focus** | Not value innovation | Eliminate/reduce while raising/creating | +| **Incrementalism** | No leap in value | Aim for 10x improvement on key factors | +| **Imitating competitors** | Red ocean thinking | Look across the six paths for alternatives | +| **Ignoring adoption** | Great idea, no execution | Plan for adoption hurdles upfront | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Does the Strategy Canvas show a different curve? | Still in the red ocean | Apply the ERRC framework | +| Are we eliminating AND creating? | Not value innovation | Use all four actions | +| Are we breaking the value-cost trade-off? | Traditional competition | Identify over-served factors to cut | +| Are we converting non-customers? | Fighting for existing share | Map the three tiers of non-customers | +| Is there a leap in buyer utility? | Incremental improvement | Aim for 10x on key utility levers | + +## Further Reading + +Based on Blue Ocean Strategy by W. Chan Kim and Renée Mauborgne: + +- [*"Blue Ocean Strategy"*](https://www.amazon.com/Blue-Ocean-Strategy-Expanded-Uncontested/dp/1625274491?tag=wondelai00-20) by W. Chan Kim & Renée Mauborgne (Expanded Edition) +- [*"Blue Ocean Shift"*](https://www.amazon.com/Blue-Ocean-Shift-Competing-Confidence/dp/0316314048?tag=wondelai00-20) by W. Chan Kim & Renée Mauborgne (practical guide to making the shift) + +## About the Authors + +**W. Chan Kim** and **Renée Mauborgne** are professors of strategy at INSEAD and co-directors of the INSEAD Blue Ocean Strategy Institute. *Blue Ocean Strategy* has sold over 4 million copies in 46 languages, making it one of the best-selling business books of all time. diff --git a/.agents/skills/blue-ocean-strategy/references/blue-ocean-examples.md b/.agents/skills/blue-ocean-strategy/references/blue-ocean-examples.md new file mode 100644 index 00000000..aaf072b5 --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/references/blue-ocean-examples.md @@ -0,0 +1,392 @@ +# Blue Ocean Case Studies + +Eight detailed case studies of companies that created blue oceans, analyzed through the lens of the Four Actions Framework (ERRC). Each case illustrates how the company escaped head-to-head competition and unlocked new demand rather than fighting for existing market share. + + +## Table of Contents +1. [Cirque du Soleil: Reinventing the Circus](#cirque-du-soleil-reinventing-the-circus) +2. [Yellow Tail: Wine for Everyone](#yellow-tail-wine-for-everyone) +3. [Nintendo Wii: Gaming for the Whole Family](#nintendo-wii-gaming-for-the-whole-family) +4. [Southwest Airlines: Flying for the Driving Class](#southwest-airlines-flying-for-the-driving-class) +5. [Netflix: From Late Fees to Streaming Empire](#netflix-from-late-fees-to-streaming-empire) +6. [Uber: Ride-Hailing Reimagined](#uber-ride-hailing-reimagined) +7. [Curves: 30-Minute Fitness for Women](#curves-30-minute-fitness-for-women) +8. [iTunes: Legal Music at a Fair Price](#itunes-legal-music-at-a-fair-price) +9. [Cross-Cutting Patterns](#cross-cutting-patterns) + +--- + +## Cirque du Soleil: Reinventing the Circus + +### Industry Context + +The traditional circus industry had been in steady decline for decades. Animal rights concerns, rising costs of star performers, and competition from television and video games eroded attendance. Ringling Bros. and Barnum & Bailey dominated a shrinking pie. + +### Red Ocean Conditions + +- Circuses competed on star performers, animal acts, and three-ring spectacle +- Rising costs of animal care, insurance, and performer salaries +- Declining audiences, especially among adults +- Price sensitivity limited revenue growth + +### Blue Ocean Move + +Cirque du Soleil blended circus arts with theater and dance, targeting adults and corporate clients willing to pay premium prices for a refined entertainment experience. They did not try to build a "better circus." They created a new category. + +### ERRC Applied + +| Action | Factors | +|--------|---------| +| **Eliminate** | Animal shows, star performers, aisle concession sales, multiple show arenas | +| **Reduce** | Fun and humor (less slapstick), thrill and danger | +| **Raise** | Unique venue atmosphere, artistic music and dance | +| **Create** | Theme-based storylines, refined watching environment, multiple distinct productions, artistic choreography | + +### Results + +- Revenue exceeded Ringling Bros. within 20 years of founding +- Ticket prices 2-3x higher than traditional circus +- Operates in over 60 countries +- Lower cost structure (no animals, no star performer salaries) + +### Lessons + +You do not need to beat the best competitor at their own game. By redefining the boundaries of the industry, Cirque du Soleil attracted theater-goers and event planners who never considered attending a circus. + +--- + +## Yellow Tail: Wine for Everyone + +### Industry Context + +The U.S. wine industry in the early 2000s was fiercely competitive. Thousands of wineries competed on terroir, awards, aging quality, and tasting complexity. Consumers faced overwhelming choice and intimidating jargon. + +### Red Ocean Conditions + +- Over 1,600 wineries competing in the U.S. market alone +- Competition on prestige, vintage quality, and expert ratings +- Wine selection was intimidating for average consumers +- Price wars at the low end; brand wars at the high end + +### Blue Ocean Move + +Casella Wines (Australia) launched Yellow Tail as a simple, fun, easy-to-drink wine that appealed to beer and cocktail drinkers, not wine connoisseurs. They stripped away everything intimidating about wine. + +### ERRC Applied + +| Action | Factors | +|--------|---------| +| **Eliminate** | Enological terminology, aging qualities, prestige marketing | +| **Reduce** | Wine complexity, vineyard prestige, wine range (started with two: red and white) | +| **Raise** | Easy drinking, retail store involvement, fun and adventure in branding | +| **Create** | Sweet, fruity taste profile accessible to non-wine-drinkers; kangaroo branding with bold colors; simplified selection | + +### Results + +- Became the fastest-growing wine brand in U.S. history +- Reached 6.5 million cases within two years +- Became the number-one imported wine in the U.S. by volume +- Created new demand from beer and cocktail drinkers + +### Lessons + +The biggest opportunity often lies in making an industry accessible to people who currently avoid it. Yellow Tail did not try to win gold medals. It won millions of customers who had never bought wine. + +--- + +## Nintendo Wii: Gaming for the Whole Family + +### Industry Context + +By 2006, the console gaming industry was locked in an arms race between Sony (PlayStation 3) and Microsoft (Xbox 360) over processing power, graphics fidelity, and hardcore gamer appeal. + +### Red Ocean Conditions + +- Escalating hardware costs to achieve top-tier graphics +- Games designed for dedicated gamers (18-34 male demographic) +- Rising development budgets ($10M-50M per title) +- Price competition on console hardware + +### Blue Ocean Move + +Nintendo refused to compete on graphics power. Instead, they introduced motion-controlled gaming that was physically intuitive and appealing to families, seniors, and non-gamers. The Wii was less powerful but far more accessible. + +### ERRC Applied + +| Action | Factors | +|--------|---------| +| **Eliminate** | Cutting-edge graphics processor, hard drive, DVD playback | +| **Reduce** | Processing power, game complexity, online multiplayer infrastructure | +| **Raise** | Fun factor, social/family gaming, physical activity | +| **Create** | Motion control (Wii Remote), Wii Sports (bundled game), active gaming (Wii Fit), appeal to non-gamers | + +### Results + +- Outsold PlayStation 3 and Xbox 360 in first two years +- Over 101 million units sold worldwide +- Attracted demographics that had never owned a console +- Lower manufacturing cost per unit than competitors + +### Lessons + +An industry's definition of "better" is often defined by incumbents for their existing customers. Nintendo redefined "better" as "more accessible and more fun for more people," which unlocked a vastly larger market. + +--- + +## Southwest Airlines: Flying for the Driving Class + +### Industry Context + +The U.S. airline industry has historically been one of the most competitive and least profitable sectors. Airlines competed on routes, classes of service, meals, lounges, and hub-and-spoke networks. + +### Red Ocean Conditions + +- Intense price competition among legacy carriers +- High fixed costs (hub infrastructure, fleet variety) +- Frequent bankruptcies across the industry +- Competition focused on business travelers and frequent flyers + +### Blue Ocean Move + +Southwest Airlines competed against car travel, not other airlines. They offered the speed of flying at prices comparable to driving, with the frequency and convenience of a bus service. Their target was people who would otherwise drive. + +### ERRC Applied + +| Action | Factors | +|--------|---------| +| **Eliminate** | Meals, seat assignments, first/business class, inter-airline transfers, hub-and-spoke routing, airport lounges | +| **Reduce** | Fare price (to near driving cost), check-in complexity | +| **Raise** | Flight frequency, on-time departures, employee friendliness, gate turnaround speed | +| **Create** | Point-to-point short-haul routes, 15-minute gate turnarounds, single aircraft type (Boeing 737), fun company culture | + +### Results + +- Consistently profitable every year for over 45 consecutive years +- Became the largest domestic carrier in the U.S. by passengers +- Stock ticker: LUV (reflecting their culture) +- Spawned imitators worldwide (Ryanair, EasyJet, AirAsia) + +### Lessons + +Your real competitor may not be who you think. Southwest did not try to beat United or American. They competed against Greyhound and the family car. Reframing who you compete against changes everything. + +--- + +## Netflix: From Late Fees to Streaming Empire + +### Industry Context + +In the late 1990s, video rental was dominated by Blockbuster with over 9,000 physical stores. Customers drove to stores, browsed shelves, rented physical media, and faced late fees if they forgot to return on time. + +### Red Ocean Conditions + +- Blockbuster controlled shelf space and prime real estate +- Late fees were a major revenue source (and customer pain point) +- Limited selection constrained by physical shelf space +- Customers accepted inconvenience as the cost of renting + +### Blue Ocean Move + +Netflix launched DVD-by-mail with no late fees and a subscription model, then pivoted to streaming, eliminating physical media entirely. Each phase represented a blue ocean shift against the current industry structure. + +### ERRC Applied + +**Phase 1: DVD-by-Mail** + +| Action | Factors | +|--------|---------| +| **Eliminate** | Late fees, physical stores, limited rental periods | +| **Reduce** | Impulse browsing (shifted to queue-based selection) | +| **Raise** | Selection breadth (100,000+ titles vs. ~3,000 in stores), convenience | +| **Create** | Subscription model, recommendation algorithm, user ratings, DVD queue | + +**Phase 2: Streaming** + +| Action | Factors | +|--------|---------| +| **Eliminate** | Physical media entirely, shipping wait times | +| **Reduce** | Per-title pricing | +| **Raise** | Instant access, personalization, cross-device viewing | +| **Create** | Original content, binge-watching model, global simultaneous release | + +### Results + +- Blockbuster filed for bankruptcy in 2010 +- Over 230 million subscribers worldwide by 2023 +- Fundamentally changed how entertainment is produced and consumed +- Created the "streaming wars" category + +### Lessons + +Blue oceans can be created in sequence. Netflix did not jump straight to streaming. They first created a blue ocean in DVD rental (eliminating late fees), then created another in streaming. The willingness to disrupt your own blue ocean before competitors do is critical. + +--- + +## Uber: Ride-Hailing Reimagined + +### Industry Context + +Urban transportation relied on licensed taxi medallions, dispatchers, street hails, and cash payments. The taxi industry in most cities was heavily regulated, with limited supply and inconsistent service quality. + +### Red Ocean Conditions + +- Fixed supply of taxi medallions limited competition +- Poor customer experience: difficulty hailing, cash-only, no accountability +- Drivers had little incentive to provide good service +- No transparency on arrival time, route, or pricing + +### Blue Ocean Move + +Uber used smartphone GPS and mobile payments to connect riders with drivers in real time, creating a transparent, cashless, rated ride experience. They turned private car owners into a distributed fleet. + +### ERRC Applied + +| Action | Factors | +|--------|---------| +| **Eliminate** | Street hailing, cash payments, dispatcher middlemen, taxi medallion requirement | +| **Reduce** | Wait uncertainty, payment friction, driver anonymity | +| **Raise** | Ride availability, vehicle cleanliness, driver accountability (ratings), price transparency | +| **Create** | Real-time GPS tracking, surge pricing (dynamic supply), driver/rider rating system, cashless payment, ride history, fare splitting | + +### Results + +- Operates in over 10,000 cities across 70+ countries +- Created the "ride-hailing" category and the "gig economy" concept +- Valued at over $80 billion at IPO +- Forced taxi regulatory reform worldwide + +### Lessons + +Technology alone does not create a blue ocean. Uber's innovation was in the business model and customer experience, not in the underlying technology (GPS and smartphones already existed). The blue ocean came from reassembling existing technologies around unmet customer needs. + +--- + +## Curves: 30-Minute Fitness for Women + +### Industry Context + +The fitness industry in the late 1990s was polarized between full-service gyms (expensive, intimidating, time-consuming) and home exercise programs (cheap but low compliance). Women were underserved by both. + +### Red Ocean Conditions + +- Gyms competed on equipment variety, classes, amenities (pools, saunas) +- High monthly fees and long-term contracts +- Intimidating environments for casual exercisers +- Low retention rates across the industry + +### Blue Ocean Move + +Curves created women-only fitness centers with a simple 30-minute circuit training program. No mirrors, no complex machines, no men, no showers. Just a quick, effective, supportive workout. + +### ERRC Applied + +| Action | Factors | +|--------|---------| +| **Eliminate** | Mirrors, locker rooms/showers, complex machines, juice bars, pools, personal trainers, male members | +| **Reduce** | Workout time (30 minutes), membership cost, facility size | +| **Raise** | Supportive atmosphere, ease of use, community feeling | +| **Create** | Women-only environment, simple hydraulic circuit machines, 30-minute complete workout, neighborhood convenience (small locations everywhere) | + +### Results + +- Grew to over 10,000 locations worldwide +- Became the largest fitness franchise in the world by location count +- Attracted women who had never joined a gym before +- Average location: 1,500 square feet (vs. 35,000+ for traditional gyms) + +### Lessons + +Reducing scope can expand market size. By offering far less than a traditional gym, Curves attracted far more customers. The women who joined Curves were not choosing between Curves and Gold's Gym. They were choosing between Curves and not exercising at all. + +--- + +## iTunes: Legal Music at a Fair Price + +### Industry Context + +By the early 2000s, the music industry was in crisis. Napster and peer-to-peer file sharing had created massive piracy. The industry responded with lawsuits and DRM (digital rights management) that punished paying customers. + +### Red Ocean Conditions + +- Record labels forced customers to buy full albums ($15-18) for one or two songs +- Piracy offered free music with better selection than legal channels +- Legal digital music services were clunky with restrictive DRM +- Artists, labels, and consumers were all dissatisfied + +### Blue Ocean Move + +Apple's iTunes Store offered legal music downloads at $0.99 per song with a simple interface, integrated with the iPod. It gave consumers what piracy offered (single songs, huge selection) within a legal, convenient framework. + +### ERRC Applied + +| Action | Factors | +|--------|---------| +| **Eliminate** | Forced album purchases, physical distribution costs, complex DRM (replaced with simpler FairPlay) | +| **Reduce** | Price per song (from $15/album to $0.99/song), search friction | +| **Raise** | Legal compliance, audio quality (vs. inconsistent pirated files), artist compensation | +| **Create** | Per-song purchasing, seamless iPod sync, curated discovery, one-click buying, consistent 30-second previews | + +### Results + +- Sold 1 million songs in the first week +- Became the world's largest music retailer by 2008 +- Sold over 25 billion songs +- Gave the music industry a viable digital business model + +### Lessons + +When an entire industry is being disrupted by an external force (piracy), the blue ocean opportunity is to offer customers what the disruptor offers but in a legitimate, better-integrated package. Apple did not fight piracy. They made legal music more convenient than piracy. + +--- + +## Cross-Cutting Patterns + +Across all eight case studies, several recurring patterns emerge that define how blue oceans are created. + +### Pattern 1: Redefine the Competitive Boundary + +None of these companies won by being "better" at the existing game. Every one of them redefined what game they were playing. + +| Company | Old Game | New Game | +|---------|----------|----------| +| Cirque du Soleil | Circus vs. circus | Entertainment experience | +| Yellow Tail | Winery vs. winery | Beverage social experience | +| Nintendo Wii | Graphics vs. graphics | Accessible family fun | +| Southwest | Airline vs. airline | Airline vs. car travel | +| Netflix | Rental store vs. store | Entertainment subscription | +| Uber | Taxi vs. taxi | On-demand transportation | +| Curves | Gym vs. gym | Quick women's fitness routine | +| iTunes | Music store vs. store | Per-song digital convenience | + +### Pattern 2: Convert Non-Customers + +Every blue ocean was built primarily on demand from people who were NOT current customers of the industry. + +- Yellow Tail: Beer and cocktail drinkers +- Nintendo Wii: Families and seniors who did not game +- Southwest: People who drove instead of flew +- Curves: Women who did not exercise +- iTunes: People who pirated instead of buying + +### Pattern 3: Eliminate Before Creating + +Cost reduction through elimination funded value creation. The companies that eliminated the most aggressively had the largest blue oceans. + +### Pattern 4: Simplify for the Mass Market + +In every case, the blue ocean offering was simpler, not more complex, than existing offerings. Complexity serves existing customers. Simplicity attracts new ones. + +### Pattern 5: Technology Is an Enabler, Not the Strategy + +Netflix, Uber, and iTunes all used technology, but their blue ocean was in the business model and customer experience redesign. Technology was the means, not the end. + +### Checklist: Is Your Strategy a Blue Ocean? + +- [ ] Does it target people who are NOT current industry customers? +- [ ] Does it eliminate factors the industry competes on? +- [ ] Does it create factors the industry has never offered? +- [ ] Is the offering simpler than what exists? +- [ ] Does the strategy canvas show a divergent curve? +- [ ] Does it break the value-cost trade-off (higher value AND lower cost)? +- [ ] Would competitors struggle to imitate it without dismantling their current model? +- [ ] Does it redefine the industry boundary rather than compete within it? diff --git a/.agents/skills/blue-ocean-strategy/references/errc-grid.md b/.agents/skills/blue-ocean-strategy/references/errc-grid.md new file mode 100644 index 00000000..cc4f6c4c --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/references/errc-grid.md @@ -0,0 +1,393 @@ +# ERRC Grid: The Four Actions Framework + +The Eliminate-Reduce-Raise-Create (ERRC) grid is the operational tool that translates blue ocean thinking into concrete strategic actions. It forces companies to pursue differentiation and low cost simultaneously by asking four questions that challenge industry logic. This reference provides a complete guide to facilitating, applying, and validating ERRC decisions. + + +## Table of Contents +1. [The Four Actions](#the-four-actions) +2. [ERRC Grid Template](#errc-grid-template) +3. [Detailed Questions for Each Action](#detailed-questions-for-each-action) +4. [Industry Examples of ERRC Applied](#industry-examples-of-errc-applied) +5. [Step-by-Step ERRC Workshop Facilitation Guide](#step-by-step-errc-workshop-facilitation-guide) +6. [Validating ERRC Decisions](#validating-errc-decisions) +7. [From ERRC to Execution: Action Planning Template](#from-errc-to-execution-action-planning-template) +8. [Common ERRC Mistakes](#common-errc-mistakes) + +--- + +## The Four Actions + +### Eliminate + +**Core question:** Which factors that the industry has long competed on should be eliminated entirely? + +These are factors the industry takes for granted but that add cost without proportional value to buyers. Elimination is the most powerful action because it simultaneously reduces cost and simplifies the offering. + +**How to identify elimination candidates:** +- Factors that exist because "we have always done it this way" +- Features that only a small minority of buyers use +- Factors that exist because competitors have them, not because buyers need them +- Compliance with industry norms that buyers do not care about +- Legacy features that served past needs but are now irrelevant + +**Warning signs that a factor should be eliminated:** +- Removing it in a test does not generate complaints +- Buyers do not mention it when describing why they buy +- It requires significant cost but does not appear in purchase criteria +- Non-customers cite it as a reason they avoid the industry + +### Reduce + +**Core question:** Which factors should be reduced well below the industry standard? + +These are factors where the industry over-delivers relative to what buyers actually need. Reduction captures the insight that "good enough" on certain dimensions frees resources for factors that matter more. + +**How to identify reduction candidates:** +- Factors where diminishing returns have set in +- Areas where the industry standard exceeds what most buyers need +- Features that increase complexity without proportional utility +- Factors that drive cost but where buyers would accept a lower level + +**The reduction test:** If you reduced this factor by 50%, would most buyers notice? Would they care enough to switch to a competitor? + +### Raise + +**Core question:** Which factors should be raised well above the industry standard? + +These are factors where the industry currently under-delivers relative to buyer expectations or latent needs. Raising them creates differentiation that buyers immediately value. + +**How to identify raise candidates:** +- Factors where customer complaints are persistent +- Dimensions where alternatives from other industries outperform your industry +- Areas where buyers have developed workarounds because the industry standard is not good enough +- Factors that correlate most strongly with buyer satisfaction and loyalty + +### Create + +**Core question:** Which factors should be created that the industry has never offered? + +These are entirely new sources of value that redefine what the offering means. Creation is what opens new demand and attracts non-customers. + +**How to identify creation opportunities:** +- Pain points in the buyer experience cycle that no one addresses +- Needs currently served by complementary products or services +- Desires expressed by non-customers that the industry does not serve +- Capabilities enabled by new technology that the industry has not applied +- Emotional or social needs in a functionally-oriented industry (or vice versa) + +## ERRC Grid Template + +Use this template to document and communicate ERRC decisions. + +``` ++----------------------------------+----------------------------------+ +| ELIMINATE | RAISE | +| | | +| 1. ________________________ | 1. ________________________ | +| Why: ____________________ | To what level: ____________ | +| Cost saved: _____________ | Investment needed: ________ | +| | | +| 2. ________________________ | 2. ________________________ | +| Why: ____________________ | To what level: ____________ | +| Cost saved: _____________ | Investment needed: ________ | +| | | +| 3. ________________________ | 3. ________________________ | +| Why: ____________________ | To what level: ____________ | +| Cost saved: _____________ | Investment needed: ________ | +| | | ++----------------------------------+----------------------------------+ +| REDUCE | CREATE | +| | | +| 1. ________________________ | 1. ________________________ | +| From/To: ________________ | What it enables: __________ | +| Cost saved: _____________ | Investment needed: ________ | +| | | +| 2. ________________________ | 2. ________________________ | +| From/To: ________________ | What it enables: __________ | +| Cost saved: _____________ | Investment needed: ________ | +| | | +| 3. ________________________ | 3. ________________________ | +| From/To: ________________ | What it enables: __________ | +| Cost saved: _____________ | Investment needed: ________ | +| | | ++----------------------------------+----------------------------------+ + +NET COST IMPACT: _____________ +NET VALUE IMPACT: _____________ +VALUE INNOVATION? (cost down + value up): YES / NO +``` + +## Detailed Questions for Each Action + +### Eliminate Deep-Dive Questions + +1. What do we offer because competitors offer it, not because buyers need it? +2. What would happen if we stopped doing this tomorrow? +3. Which features have usage rates below 10%? +4. What costs us the most but appears nowhere in buyer decision criteria? +5. Which factors exist to serve a small segment that we could choose not to serve? +6. What industry traditions or norms would a new entrant from outside the industry find absurd? +7. What do non-customers find unappealing or unnecessary about our industry? + +### Reduce Deep-Dive Questions + +1. Where do we exceed what 80% of buyers need? +2. Which specifications could we cut in half without meaningful impact? +3. Where has the industry engaged in an escalation war that buyers did not ask for? +4. What premium features do most customers pay for but rarely use? +5. Which support or service levels could be simplified? +6. Where is "good enough" genuinely good enough for the target mass market? + +### Raise Deep-Dive Questions + +1. Where do buyers consistently express frustration with the industry standard? +2. Which factors do alternatives from other industries handle better? +3. Where have buyers created workarounds because the current standard is inadequate? +4. What would it take to move customer satisfaction from 3/5 to 5/5 on key factors? +5. Which factor, if raised dramatically, would attract non-customers? +6. Where is the gap between what buyers expect and what the industry delivers widest? + +### Create Deep-Dive Questions + +1. What job is the buyer trying to accomplish before, during, and after using our product? +2. What complementary products or services do buyers currently need alongside ours? +3. What would make non-customers consider our industry for the first time? +4. What emotional or social needs are unmet by the industry's functional focus (or vice versa)? +5. What would buyers design if they could start from scratch? +6. What trends will reshape buyer expectations in the next 3-5 years? +7. What pain points exist in the buyer experience cycle that no one addresses? + +## Industry Examples of ERRC Applied + +### Technology: Zoom (Video Conferencing) + +| Eliminate | Reduce | Raise | Create | +|-----------|--------|-------|--------| +| Hardware requirements (dedicated systems) | Feature complexity for basic use | Audio/video reliability | One-click join (no account needed for guests) | +| Enterprise-only sales model | Per-minute pricing | Meeting capacity (free tier: 100 people) | Gallery view (see everyone at once) | +| Complex setup/IT deployment | Configuration options | Cross-platform compatibility | Virtual backgrounds | +| | | | Breakout rooms at scale | + +**Result:** Zoom did not invent video conferencing. It made it work reliably and removed every friction point, unlocking demand from education, social users, and small businesses who had never used video conferencing before. + +### Retail: IKEA (Furniture) + +| Eliminate | Reduce | Raise | Create | +|-----------|--------|-------|--------| +| Sales assistance on the floor | Material quality (functional, not luxury) | Design quality (Scandinavian aesthetic) | Self-service warehouse shopping | +| Home delivery (customer transports) | Furniture longevity (designed for life stages) | Range of home products | Flat-pack self-assembly | +| Assembled furniture | | In-store experience | Restaurant inside the store | +| | | Affordability | Room display showrooms | +| | | | Online planning tools | + +**Result:** IKEA serves customers who would otherwise buy cheap, poorly designed furniture or delay purchasing entirely. The self-assembly trade-off (a reduction in convenience) funds the raising of design quality and the creation of an inspiring shopping experience. + +### Healthcare: MinuteClinic (Walk-In Clinics) + +| Eliminate | Reduce | Raise | Create | +|-----------|--------|-------|--------| +| Appointments | Range of services (only common conditions) | Convenience (walk-in, no wait scheduling) | Retail location (inside CVS/pharmacy) | +| Doctor requirement (nurse practitioners) | Wait time for simple issues | Transparent pricing | Electronic health records integration | +| Full diagnostic workup | | Extended hours (evenings, weekends) | Immediate prescription fulfillment (same pharmacy) | +| Insurance complexity for simple visits | | | Online check-in and wait time visibility | + +**Result:** MinuteClinic did not compete with hospitals or primary care physicians. It served people who would otherwise skip treatment for minor issues because the traditional healthcare system was too slow, expensive, or inconvenient. + +### Education: Khan Academy (Online Learning) + +| Eliminate | Reduce | Raise | Create | +|-----------|--------|-------|--------| +| Tuition fees | In-person instruction | Accessibility (free, global) | Mastery-based progression | +| Fixed schedule | Textbook dependence | Practice exercises per concept | Personalized learning dashboard | +| Geographic limitation | | Pace flexibility (pause, rewind, repeat) | Teacher/parent monitoring tools | +| Age/grade restrictions | | Content breadth | Gamification (badges, streaks) | +| Enrollment barriers | | | Adaptive difficulty | + +**Result:** Khan Academy attracted millions of learners who could not access or afford traditional tutoring, as well as students whose in-school learning was insufficient. The elimination of tuition, schedule, and geographic barriers unlocked massive latent demand. + +## Step-by-Step ERRC Workshop Facilitation Guide + +### Preparation (1 week before) + +1. Complete the strategy canvas exercise first (the ERRC grid builds on canvas insights) +2. Gather customer data: satisfaction surveys, NPS comments, support tickets, churn reasons +3. Gather non-customer data: interviews or surveys about why people avoid the industry +4. Prepare printed ERRC grid templates (one per participant plus extras) +5. Invite 8-12 cross-functional participants + +### Workshop Agenda (3.5 hours) + +**Part 1: Context Setting (30 minutes)** + +| Time | Activity | +|------|----------| +| 0:00 | Review the strategy canvas from previous workshop | +| 0:10 | Share customer and non-customer data highlights | +| 0:20 | Introduce the ERRC framework and rules | + +**Rules to establish:** +- No factor is sacred (everything is a candidate for elimination) +- Every "raise" or "create" must be funded by an "eliminate" or "reduce" +- Think from the buyer's perspective, not internal perspective +- Non-customers matter more than existing customers for this exercise + +**Part 2: Individual ERRC Brainstorming (30 minutes)** + +Each participant fills out their own ERRC grid silently. This prevents groupthink and ensures diverse perspectives. + +**Part 3: Share and Cluster (45 minutes)** + +| Time | Activity | +|------|----------| +| 1:00 | Each person shares their top 2 items per quadrant | +| 1:15 | Facilitator clusters similar ideas on whiteboard | +| 1:30 | Group discusses and debates each cluster | +| 1:45 | Vote on top 3 items per quadrant | + +**Part 4: Break (15 minutes)** + +**Part 5: Deepen and Validate (45 minutes)** + +For each selected ERRC action, the group works through: + +| Question | Purpose | +|----------|---------| +| What is the specific cost impact? | Quantify elimination/reduction savings | +| What is the specific value impact? | Quantify raise/create value to buyers | +| What evidence supports this? | Ground decisions in data, not assumptions | +| What is the risk if we are wrong? | Identify reversible vs. irreversible decisions | +| How would competitors respond? | Assess defensibility | + +**Part 6: Draw the New Value Curve (30 minutes)** + +Using the finalized ERRC grid, draw the proposed value curve on the strategy canvas. Compare it to the current industry curves. + +**Validation checks:** +- Is the curve divergent from competitors? +- Is it focused (not trying to be high on everything)? +- Can you articulate it in one sentence (compelling tagline)? + +**Part 7: Action Planning (15 minutes)** + +For each ERRC decision, assign: +- Owner +- Timeline +- Dependencies +- Success metric + +## Validating ERRC Decisions + +Before committing to ERRC actions, validate each decision against these criteria. + +### Elimination Validation + +| Check | Pass? | +|-------|-------| +| Fewer than 20% of target buyers actively use this factor | | +| Removing it does not create legal/safety/compliance risk | | +| The cost savings are quantifiable and significant | | +| Non-customers would not be deterred by its absence | | +| A small test (removing the factor for a subset) confirms low impact | | + +### Reduction Validation + +| Check | Pass? | +|-------|-------| +| The reduced level still meets the needs of 80%+ of target buyers | | +| The cost savings from reduction are meaningful | | +| Competitors' over-investment in this factor is not what buyers love about them | | +| The reduction does not harm the factors you are raising | | + +### Raise Validation + +| Check | Pass? | +|-------|-------| +| Buyers cite this factor as a pain point or unmet need | | +| The investment is funded by elimination/reduction savings | | +| Raising this factor would attract non-customers | | +| You can sustainably deliver at this raised level | | + +### Create Validation + +| Check | Pass? | +|-------|-------| +| No competitor currently offers this | | +| Non-customers have expressed this need (directly or indirectly) | | +| The creation is feasible at the target cost structure | | +| It integrates with the raised factors to form a coherent offering | | +| First-time buyers would understand its value quickly | | + +## From ERRC to Execution: Action Planning Template + +For each ERRC action, complete this planning template. + +``` +ERRC Action: [Eliminate/Reduce/Raise/Create] [Factor Name] +-------------------------------------------------------------- +Current State: ____________________________________________ +Target State: _____________________________________________ +Timeline: ________________________________________________ +Owner: ___________________________________________________ + +Cost Impact: + - One-time cost/savings: $_______ + - Recurring annual impact: $_______ + +Value Impact: + - Which buyer segment benefits most: __________________ + - How will we measure the impact: ____________________ + +Dependencies: + - Internal: ___________________________________________ + - External: ___________________________________________ + +Risks: + - What could go wrong: ________________________________ + - Mitigation: _________________________________________ + +Success Criteria: + - We will know this worked when: ______________________ + - We will revisit if: __________________________________ +``` + +## Common ERRC Mistakes + +### Mistake 1: Eliminating What Customers Secretly Value + +Some factors appear unimportant in surveys but drive emotional attachment. Test elimination with a small cohort before full commitment. + +**Example:** A restaurant eliminates table cloths to reduce costs. Surveys never mentioned table cloths, but customers report the restaurant "feels cheaper" after the change. + +**Fix:** Run small experiments. Observe behavior, not just survey responses. + +### Mistake 2: Creating Without Demand Validation + +Teams get excited about novel features that sound innovative but address no real buyer need. Every "create" should map to a documented pain point or non-customer barrier. + +**Example:** A software company creates an AI feature because competitors are adding AI, not because users have a problem the AI solves. + +**Fix:** Every create must answer: "Which specific non-customer barrier or buyer pain point does this address?" + +### Mistake 3: Raising Everything, Eliminating Nothing + +This is the most common mistake. Teams are willing to add but reluctant to subtract. The result is a "more for more" strategy that is not value innovation. + +**Fix:** Enforce a strict rule: the number of eliminate + reduce items must equal or exceed the number of raise + create items. + +### Mistake 4: Treating ERRC as a One-Time Exercise + +Markets evolve. What you eliminate today may become important tomorrow. What you create today may become table stakes. + +**Fix:** Revisit the ERRC grid quarterly. Update the strategy canvas annually. + +### Mistake 5: Ignoring Internal Resistance + +Eliminating factors that employees have built their careers around creates organizational resistance. The ERRC grid is a strategic tool, but implementation requires change management. + +**Fix:** Involve affected teams in the ERRC workshop. Use fair process (engagement, explanation, expectation clarity) to build buy-in. + +### Mistake 6: Confusing Reduce with Eliminate + +Reduction means still offering the factor, but at a lower level. Elimination means removing it entirely. The strategic and cost implications are different. Be deliberate about which action you are taking. + +**Fix:** For each factor under consideration, explicitly ask: "Should we offer this at a lower level, or remove it completely?" The answer depends on whether any portion of the target market needs it. diff --git a/.agents/skills/blue-ocean-strategy/references/implementation.md b/.agents/skills/blue-ocean-strategy/references/implementation.md new file mode 100644 index 00000000..33b28cdc --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/references/implementation.md @@ -0,0 +1,418 @@ +# Blue Ocean Implementation + +Creating a blue ocean strategy is only half the challenge. Executing it requires organizational alignment, leadership that can mobilize change rapidly, and fair process that builds trust and voluntary cooperation. This reference covers the complete implementation journey from strategic decision to sustained execution, including how to protect blue oceans once created and how to renew them when they inevitably turn red. + + +## Table of Contents +1. [Organizational Alignment for Blue Ocean Execution](#organizational-alignment-for-blue-ocean-execution) +2. [Tipping Point Leadership](#tipping-point-leadership) +3. [Fair Process](#fair-process) +4. [Overcoming Organizational Hurdles](#overcoming-organizational-hurdles) +5. [Blue Ocean Initiative Planning Template](#blue-ocean-initiative-planning-template) +6. [Risk Assessment and Mitigation](#risk-assessment-and-mitigation) +7. [Measuring Blue Ocean Success](#measuring-blue-ocean-success) +8. [Sustaining Blue Oceans](#sustaining-blue-oceans) +9. [When Blue Oceans Turn Red: Renewal Strategies](#when-blue-oceans-turn-red-renewal-strategies) + +--- + +## Organizational Alignment for Blue Ocean Execution + +A blue ocean strategy demands that the entire organization aligns around the new value curve. This means every function (operations, marketing, sales, HR, finance) must support the ERRC decisions simultaneously. + +### The Alignment Principle + +In red ocean strategy, companies choose between differentiation and low cost, and each function optimizes for the chosen path. In blue ocean strategy, every function must simultaneously pursue both. This requires a different kind of alignment. + +| Function | Supports Eliminate/Reduce (Cost) | Supports Raise/Create (Value) | +|----------|----------------------------------|-------------------------------| +| **Operations** | Streamline processes, remove eliminated factor capabilities | Build capabilities for created factors | +| **Marketing** | Stop marketing eliminated factors | Communicate new value proposition to non-customers | +| **Sales** | Retrain away from old pitch points | Equip with new value story targeting non-customers | +| **HR** | Reassign or retrain staff from eliminated areas | Hire for new capability areas | +| **Finance** | Reallocate budgets from eliminated/reduced areas | Fund raise/create investments | +| **Product/R&D** | Stop developing eliminated features | Invest in created factors | +| **Customer Success** | Adjust support for simplified offering | Build expertise in new value areas | + +### Alignment Workshop Template + +**Objective:** Ensure every function understands and can execute the ERRC decisions. + +**Duration:** 2 hours per function (or 1 full day for all functions together) + +**For each function, complete:** + +``` +Function: _________________________ + +ELIMINATE implications: + What we stop doing: _____________________________________________ + Resources freed: ________________________________________________ + Timeline: _______________________________________________________ + +REDUCE implications: + What we do less of: _____________________________________________ + Resources freed: ________________________________________________ + Timeline: _______________________________________________________ + +RAISE implications: + What we invest more in: _________________________________________ + Resources needed: _______________________________________________ + Timeline: _______________________________________________________ + +CREATE implications: + What new capabilities we build: __________________________________ + Resources needed: _______________________________________________ + Timeline: _______________________________________________________ + +Dependencies on other functions: ____________________________________ +Risks specific to this function: ____________________________________ +``` + +## Tipping Point Leadership + +Blue ocean implementation does not require massive budgets or years of transformation. Tipping point leadership focuses on concentrating resources on the factors that have disproportionate influence, enabling rapid change with limited resources. + +### The Core Idea + +In every organization, there are people, activities, and factors that exercise disproportionate influence on performance. Tipping point leadership identifies and leverages these disproportionate factors instead of trying to change everything at once. + +### The Four Disproportionate Influence Levers + +#### Lever 1: Cognitive Hurdle (Making People See) + +**Challenge:** People do not believe change is necessary until they experience the problem firsthand. + +**Tipping point approach:** Do not rely on presentations and data. Create direct experiences. + +| Tactic | How It Works | Example | +|--------|-------------|---------| +| **Ride-along** | Have leaders experience the customer's pain directly | Police Commissioner Bill Bratton made senior NYPD officers ride the subway to experience crime firsthand | +| **Customer immersion** | Bring decision-makers face-to-face with unhappy customers or non-customers | Have executives staff the support line for a day | +| **Competitive exposure** | Show leaders the competitor or alternative that is winning | Visit a competitor's store, use their product, interview their customers | +| **Data made visceral** | Transform abstract metrics into tangible experiences | Instead of "30% churn rate," introduce leaders to 30 customers who left and let them explain why | + +**The rule:** Do not argue for change. Let people see and feel the need for change themselves. + +#### Lever 2: Resource Hurdle (Concentrating Resources) + +**Challenge:** Resources are spread thin across the organization, and there is never enough budget for transformation. + +**Tipping point approach:** Do not fight for more resources. Redistribute existing resources from cold spots (low-impact areas) to hot spots (high-impact areas). + +| Tactic | How It Works | +|--------|-------------| +| **Hot spot identification** | Find the 20% of activities that produce 80% of results and concentrate resources there | +| **Cold spot identification** | Find the 20% of activities that absorb resources but produce minimal results and redirect those resources | +| **Horse trading** | Exchange low-value resources in one area for high-value resources in another (across departments) | +| **Asset redeployment** | Repurpose assets from eliminated/reduced factors to raise/create factors | + +**The rule:** You rarely need more resources. You need to reallocate the resources you already have. + +#### Lever 3: Motivational Hurdle (Getting People to Want to Move) + +**Challenge:** Even when people understand the need and resources are available, they may lack motivation to change their behavior. + +**Tipping point approach:** Do not try to motivate the entire organization. Focus on kingpins (key influencers) and use fishbowl management (transparency that creates peer accountability). + +| Tactic | How It Works | +|--------|-------------| +| **Kingpin focus** | Identify the most influential people at every level and convert them first. Others follow. | +| **Fishbowl management** | Make performance visible to everyone. Transparency creates positive peer pressure. | +| **Atomize the challenge** | Break the transformation into small, achievable milestones. Each win builds momentum. | +| **Celebrate early wins** | Publicly recognize the first team or individual to demonstrate the new behavior. | + +**The rule:** You do not need to motivate everyone. You need to motivate the right people, and transparency does the rest. + +#### Lever 4: Political Hurdle (Silencing Opposition) + +**Challenge:** Powerful insiders who benefit from the status quo will actively work to undermine the blue ocean strategy. + +**Tipping point approach:** Identify and neutralize political opposition before it gains momentum. + +| Tactic | How It Works | +|--------|-------------| +| **Map the political landscape** | Identify who benefits from the status quo and who benefits from change | +| **Secure a consigliere** | Find a respected insider who supports the change and can advise on political dynamics | +| **Build a coalition** | Unite supporters across the organization before opponents can organize | +| **Isolate blockers** | Do not fight opponents publicly. Remove their ability to block by going around them or above them | +| **Offer a role in the future** | Some opponents can be converted by giving them a meaningful role in the new strategy | + +**The rule:** Do not ignore politics. Map them, manage them, and move fast enough that opposition cannot organize. + +## Fair Process + +Fair process is the execution mechanism that builds trust and voluntary cooperation during blue ocean implementation. Without fair process, even the best strategy will face internal resistance. + +### The Three Principles of Fair Process + +#### Principle 1: Engagement + +**What it means:** Involve people in strategic decisions that affect them. Ask for their input. Allow them to challenge and refine ideas. + +**What it does NOT mean:** Consensus. Democracy. Letting everyone vote. Engagement means input and influence, not control. + +**How to practice engagement:** +- Include front-line employees in ERRC workshops +- Present the draft strategy and invite critique before finalizing +- Ask "What are we missing?" and genuinely listen +- Involve affected teams in designing their own transition plan + +#### Principle 2: Explanation + +**What it means:** Explain the reasoning behind strategic decisions so that everyone understands WHY, even if they disagree with WHAT. + +**How to practice explanation:** +- Share the non-customer research that drives the strategy +- Explain the competitive logic behind each ERRC decision +- Be transparent about trade-offs and what is being sacrificed +- Address the "why now" question directly + +#### Principle 3: Expectation Clarity + +**What it means:** State clearly what is expected of everyone after the decision. What are the new rules? What are the new metrics? What does success look like? + +**How to practice expectation clarity:** +- Define new roles and responsibilities explicitly +- Set clear milestones and deadlines +- Communicate new performance metrics before they take effect +- Make sure every person knows what they are expected to do differently + +### Fair Process Assessment + +Rate your implementation plan on each dimension (1-5): + +| Dimension | Rating (1-5) | Evidence | +|-----------|-------------|---------| +| Have affected employees been involved in shaping the strategy? | | | +| Has the reasoning behind the strategy been clearly communicated? | | | +| Do all employees know what is expected of them? | | | +| Are new metrics and goals clearly defined and communicated? | | | +| Have concerns and objections been heard and addressed? | | | +| Is there a feedback mechanism for ongoing input? | | | + +**If any dimension scores below 3:** Address it before proceeding with implementation. Low fair process scores predict high resistance and poor execution. + +## Overcoming Organizational Hurdles + +### Hurdle 1: Cognitive Hurdle + +**Symptom:** "We do not see why we need to change. Things are fine." + +| Action | Owner | Timeline | +|--------|-------|----------| +| Schedule customer ride-alongs for leadership team | | | +| Arrange non-customer interviews attended by executives | | | +| Create a "day in the life" video of a frustrated customer | | | +| Present competitor/alternative analysis with real user quotes | | | + +### Hurdle 2: Resource Hurdle + +**Symptom:** "We do not have the budget or people for this." + +| Action | Owner | Timeline | +|--------|-------|----------| +| Audit current resource allocation for cold spots | | | +| Identify resources tied to eliminated/reduced factors | | | +| Propose resource reallocation plan (from cold spots to hot spots) | | | +| Identify partnership opportunities to fill capability gaps | | | + +### Hurdle 3: Motivational Hurdle + +**Symptom:** "People understand the strategy but are not changing their behavior." + +| Action | Owner | Timeline | +|--------|-------|----------| +| Identify kingpins at every organizational level | | | +| Design a fishbowl dashboard showing progress transparently | | | +| Break the transformation into 30-day sprints with clear milestones | | | +| Plan public celebrations for early wins | | | + +### Hurdle 4: Political Hurdle + +**Symptom:** "Key people are actively or passively blocking the strategy." + +| Action | Owner | Timeline | +|--------|-------|----------| +| Map the political landscape (supporters, opponents, neutrals) | | | +| Identify and secure a consigliere | | | +| Build coalition of supporters before formal launch | | | +| Develop a plan for each identified blocker | | | + +## Blue Ocean Initiative Planning Template + +Use this template to plan the complete implementation of a blue ocean strategy. + +``` +BLUE OCEAN INITIATIVE PLAN +=========================== + +Initiative Name: _______________________________________________ +Strategic Price: _______________________________________________ +Target Cost: __________________________________________________ +Target Launch Date: ____________________________________________ +Initiative Owner: ______________________________________________ + +PHASE 1: FOUNDATION (Weeks 1-4) +--------------------------------- +[ ] Finalize ERRC grid with cross-functional input +[ ] Complete alignment workshops for all functions +[ ] Identify and address adoption hurdles +[ ] Secure executive sponsor and consigliere +[ ] Map political landscape and build coalition +[ ] Define new metrics and success criteria +[ ] Communicate strategy with fair process (engagement, explanation, clarity) + +PHASE 2: BUILD (Weeks 5-12) +--------------------------------- +[ ] Begin eliminating identified factors +[ ] Begin reducing identified factors +[ ] Build capabilities for raised factors +[ ] Develop created factors (MVP/pilot version) +[ ] Reallocate resources from cold spots to hot spots +[ ] Establish partnerships for cost/capability gaps +[ ] Develop go-to-market plan targeting non-customers + +PHASE 3: PILOT (Weeks 13-16) +--------------------------------- +[ ] Launch pilot with limited audience +[ ] Measure buyer utility (does the utility leap land?) +[ ] Validate pricing (do non-customers convert at this price?) +[ ] Confirm cost structure (is target cost achievable?) +[ ] Gather feedback and iterate +[ ] Address unexpected adoption hurdles + +PHASE 4: SCALE (Weeks 17-24) +--------------------------------- +[ ] Full launch based on pilot learnings +[ ] Ramp marketing to non-customer segments +[ ] Scale operations for new offering +[ ] Monitor competitive response +[ ] Track blue ocean metrics (see below) +[ ] Celebrate wins and reinforce the new direction + +PHASE 5: SUSTAIN (Ongoing) +--------------------------------- +[ ] Monitor for competitive imitation +[ ] Track value curve convergence (competitors copying) +[ ] Continuously refine based on customer feedback +[ ] Plan for blue ocean renewal when needed +``` + +## Risk Assessment and Mitigation + +### Blue Ocean Risk Matrix + +| Risk | Likelihood (1-5) | Impact (1-5) | Score | Mitigation | +|------|-------------------|---------------|-------|------------| +| Non-customers do not convert as expected | | | | Validate with pilot; adjust utility/price | +| Target cost is not achievable | | | | More aggressive elimination; seek partnerships | +| Employees resist elimination of familiar factors | | | | Fair process; kingpin focus; gradual transition | +| Competitors imitate quickly | | | | Price low enough to discourage entry; build switching costs | +| Partners refuse to adapt | | | | Find new partners; vertical integration if needed | +| Regulatory barriers emerge | | | | Proactive engagement; self-regulation | +| Technology does not deliver promised utility | | | | Prototype early; MVP validation before commitment | +| Market timing is wrong (too early) | | | | Pilot in receptive segment; build optionality | + +### Risk Prioritization + +Score = Likelihood x Impact. Address risks with scores above 12 first. + +## Measuring Blue Ocean Success + +Traditional metrics (market share, competitive win rate) are red ocean metrics. Blue ocean strategies need different measures. + +### Blue Ocean Metrics Dashboard + +| Metric | What It Measures | Target | +|--------|-----------------|--------| +| **Non-customer conversion rate** | % of targeted non-customers who adopt | > ___% | +| **New demand created** | Revenue from buyers who were not in the market before | > $_____ | +| **Value curve divergence** | Degree of difference from competitor curves (strategy canvas) | Maintain divergence | +| **Cost-value gap** | Ratio of cost reduction to value increase | Cost down, value up | +| **Buyer utility score** | Customer-reported utility leap (survey) | > ___/10 | +| **Time to adoption** | How quickly new buyers understand and adopt | < ___ days | +| **Organic referral rate** | % of new customers from word-of-mouth | > ___% | +| **Competitive imitation lag** | Time before competitors launch similar offerings | > ___ months | +| **Price corridor position** | Whether pricing remains within the mass corridor | Within corridor | +| **Employee alignment score** | Internal survey on strategy understanding and commitment | > ___/10 | + +## Sustaining Blue Oceans + +### Why Blue Oceans Eventually Turn Red + +Every successful blue ocean attracts imitators. Over time, competitors adopt similar ERRC moves, value curves converge, and the blue ocean becomes red. This is inevitable. The question is not whether it will happen, but how long you can sustain the blue ocean and whether you can create the next one before the current one turns red. + +### Barriers to Imitation + +Blue ocean strategies have natural barriers that slow imitation: + +| Barrier | How It Works | Duration | +|---------|-------------|----------| +| **Brand perception** | First-mover in a new category owns the brand association | 5-10 years | +| **Network effects** | More users = more value (Uber, Airbnb) | Long-lasting if strong | +| **Organizational misfit** | Competitors would need to dismantle their current model to imitate | 3-7 years | +| **Economic deterrence** | Low pricing makes the blue ocean unattractive to high-cost competitors | Depends on cost structure | +| **Legal protection** | Patents, exclusive partnerships, regulatory approvals | Duration of protection | +| **Learning curve** | Tacit knowledge and operational expertise take time to develop | 2-5 years | +| **Ecosystem lock-in** | Partners, integrations, and complementary products create switching costs | Grows over time | + +### Strategies for Extending Blue Ocean Duration + +1. **Continuously improve the created/raised factors.** Do not rest after launch. Keep widening the gap on the factors that define your blue ocean. + +2. **Raise switching costs organically.** Build features that increase in value over time (data, customization, network effects). + +3. **Monitor the strategy canvas quarterly.** When competitors start to converge on your curve, you are losing blue ocean status. + +4. **Stay connected to non-customers.** As your blue ocean matures, new tiers of non-customers emerge. Convert them to extend the ocean. + +5. **Price to deter entry.** If you have cost advantages from elimination/reduction, price low enough that imitators cannot profitably enter. + +## When Blue Oceans Turn Red: Renewal Strategies + +### Recognizing the Red Tide + +| Signal | What It Means | +|--------|--------------| +| Value curves converging | Competitors are imitating your ERRC moves | +| Non-customer conversion slowing | The easy tiers of non-customers have been captured | +| Price competition intensifying | The market is maturing and commoditizing | +| Marketing costs rising | You need to spend more to achieve the same awareness | +| Growth rate declining | The blue ocean is becoming a red ocean | +| Customer satisfaction plateauing | The utility leap is becoming the new standard | + +### Renewal Options + +#### Option 1: Create a New Blue Ocean Within the Same Industry + +Go back to the Six Paths Framework and ERRC grid. The industry has changed since you created the first blue ocean. New non-customers exist. New technology enables new possibilities. New trends create new opportunities. + +**Example:** Apple created successive blue oceans: iPod (music), iPhone (mobile), iPad (tablet), Apple Watch (wearable), AirPods (audio). + +#### Option 2: Extend the Blue Ocean to New Geographies or Segments + +Your blue ocean strategy may still be novel in markets or segments you have not yet entered. + +**Example:** Netflix extended its blue ocean from the U.S. to international markets, adapting content but maintaining the core value innovation. + +#### Option 3: Deepen the Blue Ocean with Platform/Ecosystem Strategy + +Transform the offering from a product into a platform or ecosystem that creates ongoing value and lock-in. + +**Example:** Salesforce evolved from a simple CRM into a platform (Force.com) and ecosystem (AppExchange), creating layers of value that kept the blue ocean from turning red. + +#### Option 4: Harvest and Invest + +If the blue ocean is irreversibly turning red, harvest profits from the maturing business and invest them in discovering the next blue ocean. Do not pour resources into defending a reddening ocean. + +### Blue Ocean Renewal Checklist + +- [ ] Are you monitoring value curve convergence quarterly? +- [ ] Do you have a process for continuous non-customer analysis? +- [ ] Is there a dedicated team or time for exploring the next blue ocean? +- [ ] Are you investing in the created/raised factors, not the eliminated ones? +- [ ] Can you articulate what the next blue ocean might be? +- [ ] Is your organization prepared to cannibalize its own blue ocean before competitors do? +- [ ] Do you have the financial reserves to fund the next shift? +- [ ] Are your leaders rewarded for blue ocean creation, not just red ocean optimization? diff --git a/.agents/skills/blue-ocean-strategy/references/non-customers.md b/.agents/skills/blue-ocean-strategy/references/non-customers.md new file mode 100644 index 00000000..e5cba0e1 --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/references/non-customers.md @@ -0,0 +1,332 @@ +# Three Tiers of Non-Customers + +Blue oceans are built on new demand, not on stealing market share from competitors. The largest untapped opportunity for any business lies in the people who are NOT its customers. W. Chan Kim and Renee Mauborgne identified three tiers of non-customers, each representing a different distance from your current market. Understanding and converting these non-customers is how blue oceans generate explosive growth. + + +## Table of Contents +1. [Why Non-Customers Matter More Than Customers](#why-non-customers-matter-more-than-customers) +2. [The Three Tiers](#the-three-tiers) +3. [Non-Customer Analysis Worksheet](#non-customer-analysis-worksheet) +4. [Interview Guides for Each Tier](#interview-guides-for-each-tier) +5. [Case Studies of Non-Customer Conversion](#case-studies-of-non-customer-conversion) +6. [From Non-Customers to Market Sizing](#from-non-customers-to-market-sizing) +7. [Non-Customer Conversion Checklist](#non-customer-conversion-checklist) +8. [Common Mistakes in Non-Customer Analysis](#common-mistakes-in-non-customer-analysis) + +--- + +## Why Non-Customers Matter More Than Customers + +Most companies obsess over existing customers: satisfaction scores, retention rates, share of wallet. This focus is important for operational excellence, but it is the wrong starting point for strategic innovation. + +**The math of non-customers:** + +| Metric | Typical Industry | +|--------|-----------------| +| Your market share | 5-30% of existing market | +| Existing market | 10-40% of potential market | +| Your actual reach | 0.5-12% of potential demand | +| Non-customers available | 88-99.5% of potential demand | + +The ocean of non-customers is almost always larger than the pool of existing customers. Even a small conversion rate from non-customers can dwarf the gains from winning competitors' customers. + +## The Three Tiers + +### Tier 1: "Soon-to-Be" Non-Customers + +**Who they are:** People sitting on the edge of your market. They use your industry's offerings minimally, out of necessity, while actively searching for something better. They are mentally one foot out the door. + +**Characteristics:** +- They use the industry's product/service, but reluctantly +- They are the first to leave when an alternative appears +- Their usage is minimal: lowest tier, least frequent, smallest purchase +- They often express dissatisfaction but continue because they see no alternative +- They show declining engagement over time + +**How to spot them:** +- Customers on the cheapest plan who never upgrade +- Buyers who purchase only when absolutely necessary +- Users with declining usage patterns +- Customers who complain but stay (for now) +- People who use your product for a narrow subset of its capability + +**Real-World Example: Pret A Manger** + +Tier 1 non-customers of fast food were busy professionals who ate at fast food chains reluctantly because they needed speed but wanted healthier, fresher options. They were "soon-to-be" non-customers of fast food, ready to leave the moment a better option appeared. Pret offered fresh, premium-quality food at fast-food speed, converting these reluctant fast-food buyers into loyal customers of a new category. + +**Real-World Example: Spotify** + +Tier 1 non-customers of music purchasing were people who bought one or two songs per month on iTunes but found per-song pricing frustrating. They wanted more music but did not want to pay $0.99-1.29 per track. Spotify's unlimited streaming subscription converted these minimal purchasers into heavy consumers. + +### Tier 2: "Refusing" Non-Customers + +**Who they are:** People who have consciously evaluated your industry's offerings and rejected them. They are aware of what you offer but have decided it is not for them. They either use an alternative from a different industry or go without. + +**Characteristics:** +- They have considered your industry and said "no" +- They can articulate specific reasons for their refusal +- They may have tried the industry once and not returned +- They use workarounds or alternatives from other industries +- They see the industry's offerings as unacceptable, unaffordable, or irrelevant + +**How to spot them:** +- People who tried your product/industry once and never came back +- People who use clearly inferior alternatives for reasons they can explain +- People who say "I looked into it, but..." +- People who use manual/DIY solutions instead of the industry's offerings +- Former customers who left and never returned + +**Real-World Example: JCDecaux** + +Cities were Tier 2 non-customers of outdoor advertising. Municipal governments had evaluated billboard-style advertising and rejected it: too ugly, too commercial, too costly to maintain. JCDecaux created a blue ocean by offering free, beautifully designed bus shelters with integrated advertising panels. Cities got free street furniture and maintenance. JCDecaux got premium advertising space. The "refusing" non-customers became enthusiastic partners. + +**Real-World Example: Robinhood** + +Tier 2 non-customers of stock brokerage were young people who knew about investing but refused because of high commissions ($7-10 per trade), complex platforms, and account minimums. Robinhood eliminated commissions, removed minimums, and created a mobile-first, simple interface. Millions of people who had refused brokerage services became active traders. + +### Tier 3: "Unexplored" Non-Customers + +**Who they are:** People in markets distant from yours who have never considered your industry's offerings as an option. They are the furthest from your current market, and the industry has never targeted or thought about them. + +**Characteristics:** +- They have never considered your industry as a possible solution +- They may not even know your industry exists in the form it takes +- Their needs are being met (or not met) by something completely different +- The industry has assumed these people are "not our market" +- They represent the largest potential pool but require the biggest strategic shift to reach + +**How to spot them:** +- Demographic groups the industry has never targeted +- Geographic markets the industry has never entered +- Use cases the industry has never considered +- People solving the underlying need in a completely different way +- People who do not solve the underlying need at all (non-consumption) + +**Real-World Example: Callaway Big Bertha** + +The golf equipment industry was entirely focused on serious golfers who played regularly. Tier 3 non-customers were occasional golfers and complete beginners who found traditional clubs difficult to use. Callaway's Big Bertha driver had an oversized head that made it much easier to hit the ball, converting people who had never considered buying premium golf equipment into buyers. + +**Real-World Example: Nintendo Wii** + +Tier 3 non-customers of gaming consoles were families, seniors, and non-gamers who had never considered buying a game console. The industry had always assumed these people were simply "not gamers." Nintendo's motion-controlled Wii attracted tens of millions of people who had never owned a console, creating an entirely new market segment. + +## Non-Customer Analysis Worksheet + +Use this worksheet to systematically analyze non-customers for your business. + +### Section 1: Identify Non-Customers by Tier + +**Tier 1: Soon-to-Be Non-Customers** + +| Question | Your Answer | +|----------|-------------| +| Who uses our product/industry reluctantly? | | +| Who is on the cheapest plan or buys the minimum? | | +| Who shows declining engagement? | | +| What are their stated frustrations? | | +| What would make them leave? | | +| Estimated size of this tier | | + +**Tier 2: Refusing Non-Customers** + +| Question | Your Answer | +|----------|-------------| +| Who has evaluated our industry and said no? | | +| What reasons do they give for refusing? | | +| What alternatives or workarounds do they use instead? | | +| What would have to change for them to reconsider? | | +| Who tried our industry once and did not return? | | +| Estimated size of this tier | | + +**Tier 3: Unexplored Non-Customers** + +| Question | Your Answer | +|----------|-------------| +| Who has the underlying need but has never considered our industry? | | +| What demographic groups does our industry ignore? | | +| Who solves this need in a completely different way? | | +| Who does not solve this need at all (non-consumption)? | | +| What assumptions does our industry hold about "who our market is"? | | +| Estimated size of this tier | | + +### Section 2: Find Commonalities Across Tiers + +The most powerful blue ocean insights come from finding common threads across all three tiers. + +| Commonality Theme | Tier 1 Evidence | Tier 2 Evidence | Tier 3 Evidence | +|-------------------|-----------------|-----------------|-----------------| +| Too expensive | | | | +| Too complex | | | | +| Too time-consuming | | | | +| Too intimidating | | | | +| Wrong format/channel | | | | +| Missing key feature | | | | +| Other: _________ | | | | + +**The strongest blue ocean opportunities address barriers that appear across all three tiers.** If Tier 1 customers find the product too complex, Tier 2 refused because it was too complex, and Tier 3 never considered it because the category seems complex, then radical simplification is likely the path to a blue ocean. + +## Interview Guides for Each Tier + +### Tier 1 Interview Guide (Current Minimal Users) + +**Recruitment:** Identify customers with the lowest usage, cheapest plans, or declining engagement. + +**Duration:** 30-45 minutes + +**Questions:** + +1. How often do you use [product/service]? Has that changed over time? +2. What do you use it for? What do you NOT use it for? +3. When you use it, what frustrates you most? +4. If you could change three things about it, what would they be? +5. What alternatives have you considered or tried? +6. What would make you use it more often? +7. What would make you stop using it entirely? +8. If this product/service did not exist, what would you do instead? +9. How does using this make you feel? (frustrated, satisfied, indifferent?) +10. What do you wish existed that does not? + +**Listen for:** Specific friction points, declining emotional investment, awareness of alternatives, conditional loyalty ("I stay because..."). + +### Tier 2 Interview Guide (Conscious Refusers) + +**Recruitment:** Find people through surveys, social media, or referrals who have evaluated your industry and chosen not to participate. + +**Duration:** 30-45 minutes + +**Questions:** + +1. Tell me about the time you considered [industry/product]. What prompted you to look into it? +2. What did you find when you evaluated it? +3. What specifically made you decide not to go ahead? +4. What are you doing instead to meet that need? +5. How well does your current alternative work? What is its biggest limitation? +6. What would the [industry/product] need to offer for you to reconsider? +7. What is the single biggest barrier to your participation? +8. If someone designed the perfect solution for your needs, what would it look like? +9. What do people in your situation generally do about this need? +10. Is there anything about [industry] that you find unnecessary or off-putting? + +**Listen for:** Specific rejection reasons, the gap between what the industry offers and what this person needs, emotional barriers (intimidation, distrust), practical barriers (cost, time, access). + +### Tier 3 Interview Guide (Unexplored Non-Customers) + +**Recruitment:** This is the hardest group to find. Look for people in adjacent markets, different demographics, or different geographies. + +**Duration:** 20-30 minutes (shorter because they have less context) + +**Questions:** + +1. When you need to [job-to-be-done], what do you do? +2. Have you ever heard of [industry/product]? What do you know about it? +3. Why have you never considered using [industry/product]? +4. What would have to be true for you to consider it? +5. What is the biggest challenge you face with [underlying need]? +6. How do you currently solve that challenge? +7. If I told you there was a [product/service] that could [key benefit], would that interest you? What questions would you have? +8. What is the most you would be willing to pay/spend for a solution to [need]? +9. Where would you expect to find or buy such a solution? +10. What would make you tell your friends about a solution like this? + +**Listen for:** Complete lack of awareness (or misconceptions) about the industry, the underlying need they do have, what form factor or channel would reach them, price sensitivity relative to the alternatives they currently use. + +## Case Studies of Non-Customer Conversion + +### Case Study: Curves (Fitness) + +| Tier | Non-Customer Group | Barrier | How Curves Addressed It | +|------|-------------------|---------|------------------------| +| 1 | Women with gym memberships who rarely went | Intimidating environment, time commitment | Women-only, 30-minute circuit, no mirrors | +| 2 | Women who tried gyms and quit | Too complex, too expensive, too intimidating | Simplified machines, low cost, supportive community | +| 3 | Women who never considered a gym | Believed gyms "are not for people like me" | Neighborhood locations, non-gym atmosphere, word-of-mouth from friends | + +**Commonality across tiers:** All three groups shared a feeling that traditional gyms were not designed for them. Curves built its entire offering around this shared barrier. + +### Case Study: Uber (Transportation) + +| Tier | Non-Customer Group | Barrier | How Uber Addressed It | +|------|-------------------|---------|----------------------| +| 1 | Occasional taxi users who found cabs frustrating | Unpredictable wait, cash-only, no accountability | Real-time tracking, cashless, ratings | +| 2 | People who refused taxis due to cost or availability | Too expensive for regular use, unavailable outside city centers | Surge pricing transparency, UberX pricing below taxis, wider coverage | +| 3 | People in areas with no taxi service at all | No taxis exist in their area | Enabled drivers in any area with a car to provide service | + +**Commonality across tiers:** Lack of reliability and transparency. All three groups wanted to know: How long will it take? How much will it cost? Will the experience be acceptable? + +## From Non-Customers to Market Sizing + +Understanding non-customers transforms market sizing from a "TAM/SAM/SOM" spreadsheet exercise into a strategic tool. + +### Traditional Market Sizing (Red Ocean Thinking) + +``` +Total Addressable Market (TAM): All people currently buying in the industry +Serviceable Addressable Market (SAM): The segment you can reach +Serviceable Obtainable Market (SOM): The share you can realistically win +``` + +This approach only counts existing customers and divides them among existing competitors. It is zero-sum. + +### Blue Ocean Market Sizing + +``` +Current Market: Existing industry customers +Tier 1 Expansion: Soon-to-be non-customers convertible with small changes +Tier 2 Expansion: Refusing non-customers convertible with barrier removal +Tier 3 Expansion: Unexplored non-customers convertible with reframing +Blue Ocean TAM = Current Market + Tier 1 + Tier 2 + Tier 3 +``` + +### Market Sizing Template + +| Segment | Estimated Size | Conversion Requirements | Revenue Potential | +|---------|---------------|------------------------|-------------------| +| Current market customers | | Already buying | | +| Tier 1: Soon-to-be non-customers | | Small offering adjustments | | +| Tier 2: Refusing non-customers | | Barrier removal, ERRC changes | | +| Tier 3: Unexplored non-customers | | Category reframing | | +| **Blue Ocean TAM** | | | | + +### Sizing Tips + +- Tier 1 is usually 1-3x the size of your current customer base +- Tier 2 is often 3-10x the size of the current market +- Tier 3 can be 10-100x the size of the current market (but hardest to convert) +- Start with Tier 1 for quick wins, then expand to Tier 2 and Tier 3 +- Use non-customer interviews to validate size estimates + +## Non-Customer Conversion Checklist + +Before finalizing your blue ocean strategy, verify: + +- [ ] You have identified and sized all three tiers of non-customers +- [ ] You have conducted interviews with at least 5 people per tier +- [ ] You have found commonalities across tiers (shared barriers) +- [ ] Your ERRC grid directly addresses the top non-customer barriers +- [ ] Your strategy canvas divergent curve would appeal to non-customers +- [ ] Your pricing is accessible to the mass of non-customers (not just Tier 1) +- [ ] You have estimated the market expansion potential from each tier +- [ ] Your go-to-market strategy reaches non-customers (not just existing channels) +- [ ] You have identified which tier to target first for fastest validation +- [ ] Your value proposition can be explained in terms non-customers understand (no industry jargon) + +## Common Mistakes in Non-Customer Analysis + +### Mistake 1: Treating Non-Customers as Monolithic + +The three tiers have fundamentally different barriers and different conversion requirements. A strategy that converts Tier 1 may do nothing for Tier 3. Analyze each tier separately before looking for commonalities. + +### Mistake 2: Asking Existing Customers About Non-Customers + +Your current customers cannot tell you why non-customers refuse your industry. You must talk directly to non-customers. Current customers have a survivorship bias that blinds them to the barriers others face. + +### Mistake 3: Assuming Non-Customers Cannot Afford Your Product + +Cost is sometimes the barrier, but often it is not. Many Tier 2 non-customers have the money but find the offering irrelevant, intimidating, or inconvenient. Do not default to "make it cheaper" without understanding the real barrier. + +### Mistake 4: Focusing Only on Tier 1 + +Tier 1 is the easiest to reach but the smallest expansion. The biggest blue oceans come from Tier 2 and Tier 3 conversion. Do not stop at the edge of your current market. + +### Mistake 5: Ignoring Non-Consumption + +The most powerful form of Tier 3 non-customers are people who simply do not address the need at all. They are not using an alternative. They are living without a solution. This "non-consumption" represents pure new demand. diff --git a/.agents/skills/blue-ocean-strategy/references/sequence.md b/.agents/skills/blue-ocean-strategy/references/sequence.md new file mode 100644 index 00000000..1c5c836e --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/references/sequence.md @@ -0,0 +1,376 @@ +# Strategic Sequence of Blue Ocean Strategy + +A blue ocean idea must pass through four sequential tests before it becomes a commercially viable strategy: Buyer Utility, Strategic Price, Target Cost, and Adoption. Each test is a gate. If the idea fails at any gate, it must be reworked before proceeding. Skipping a gate or reversing the order leads to strategies that look promising on paper but fail in the market. + + +## Table of Contents +1. [The Four-Gate Sequence](#the-four-gate-sequence) +2. [Gate 1: Buyer Utility Map](#gate-1-buyer-utility-map) +3. [Gate 2: Strategic Pricing](#gate-2-strategic-pricing) +4. [Gate 3: Target Cost](#gate-3-target-cost) +5. [Gate 4: Adoption Hurdles](#gate-4-adoption-hurdles) +6. [Sequence Validation Checklist](#sequence-validation-checklist) +7. [Common Sequencing Mistakes](#common-sequencing-mistakes) + +--- + +## The Four-Gate Sequence + +``` +Gate 1 Gate 2 Gate 3 Gate 4 +BUYER --> STRATEGIC --> TARGET --> ADOPTION +UTILITY PRICE COST HURDLES + +Is there Is pricing Can we hit Can we overcome +exceptional accessible to target cost adoption +buyer utility? mass buyers? and profit? hurdles? + +If NO: If NO: If NO: If NO: +Rethink the Rethink the Rethink the Rethink the +offering price point cost structure rollout plan +``` + +The sequence is deliberate. Utility comes first because without a leap in buyer value, pricing and cost are irrelevant. Price comes second because it determines the cost target. Cost comes third because it must be derived from price, not the other way around. Adoption comes last because it addresses the organizational and market barriers to execution. + +## Gate 1: Buyer Utility Map + +The Buyer Utility Map is a 6x6 matrix that systematically identifies where the biggest opportunities for utility innovation exist. It crosses six utility levers (what kind of value) with six stages of the buyer experience cycle (when value is delivered). + +### The Six Utility Levers + +| Lever | Definition | Example | +|-------|-----------|---------| +| **Customer Productivity** | Helps buyers do things faster, easier, or more effectively | Google Search vs. library research | +| **Simplicity** | Reduces complexity, eliminates confusion, makes things intuitive | iPhone vs. Blackberry interface | +| **Convenience** | Available when and where buyers need it, less effort required | ATMs vs. bank teller visits | +| **Risk Reduction** | Reduces financial, physical, or emotional risk | Money-back guarantees, free trials | +| **Fun and Image** | Makes the experience enjoyable or enhances the buyer's image | Tesla (driving is fun + green image) | +| **Environmental Friendliness** | Reduces environmental impact | Patagonia (outdoor gear + environmental mission) | + +### The Six Buyer Experience Stages + +| Stage | What Happens | Key Questions | +|-------|-------------|---------------| +| **1. Purchase** | How buyers find, evaluate, and buy | How long does it take to find the product? Is buying easy? Is the transaction secure? | +| **2. Delivery** | How the product/service reaches the buyer | How long does delivery take? How difficult is unpacking and setup? | +| **3. Use** | The core experience of using the product | Does it require training? Is it intuitive? Does it deliver on promises? | +| **4. Supplements** | Other products/services needed alongside | What else does the buyer need? How easy is it to obtain supplements? | +| **5. Maintenance** | Upkeep, updates, servicing | Does it require maintenance? How easy and affordable is servicing? | +| **6. Disposal** | End-of-life, replacement, switching | Is it easy to dispose of? Are there environmental concerns? Can data be transferred? | + +### The Buyer Utility Map Template + +Rate each cell: How well does the industry currently deliver utility here? (1 = poorly, 5 = excellently) + +| | Purchase | Delivery | Use | Supplements | Maintenance | Disposal | +|--|----------|----------|-----|-------------|-------------|----------| +| **Productivity** | | | | | | | +| **Simplicity** | | | | | | | +| **Convenience** | | | | | | | +| **Risk Reduction** | | | | | | | +| **Fun and Image** | | | | | | | +| **Environmental** | | | | | | | + +**How to use the map:** +1. Fill in the matrix with industry-current scores (1-5) +2. Circle all cells rated 1-2 (these are the biggest utility gaps) +3. For each low-rated cell, ask: "What blocks utility here? What would a 5 look like?" +4. Prioritize the 3-5 cells where improvement would have the greatest impact on buyer behavior +5. Design your offering to deliver a leap in utility in those specific cells + +### Buyer Utility Map Example: Traditional Banking + +| | Purchase | Delivery | Use | Supplements | Maintenance | Disposal | +|--|----------|----------|-----|-------------|-------------|----------| +| **Productivity** | 2 (slow applications) | 2 (days to open) | 3 | 2 (separate products) | 2 (branch visits) | 2 (hard to close) | +| **Simplicity** | 1 (complex forms) | 2 (paperwork) | 3 | 2 (confusing fees) | 2 (hard to reach) | 1 (switching is hard) | +| **Convenience** | 2 (branch hours) | 2 (branch required) | 3 (ATM, online) | 2 | 2 | 2 | +| **Risk Reduction** | 4 (FDIC insured) | 4 | 4 | 3 | 3 | 2 | +| **Fun and Image** | 1 | 1 | 1 | 1 | 1 | 1 | +| **Environmental** | 1 (paper) | 1 (paper) | 2 | 1 | 1 | 1 | + +**Blue ocean opportunity (neo-bank):** The cells rated 1-2 cluster around simplicity, convenience, productivity, and fun across purchase, delivery, maintenance, and disposal stages. This is exactly where digital-first banks like Chime or Revolut created their blue oceans. + +## Gate 2: Strategic Pricing + +### The Principle + +Strategic pricing in blue ocean strategy is fundamentally different from conventional pricing. You do not start with cost and add a margin. You do not benchmark against direct competitors. You price against all alternatives that buyers consider, including options from other industries. + +### Step 1: Identify the Price Corridor of the Mass + +The "price corridor of the mass" captures the price range that attracts the largest pool of target buyers. + +**Mapping the corridor:** + +List all alternatives buyers consider (not just direct competitors): + +| Alternative | Type | Price Range | Volume of Buyers | +|-------------|------|-------------|-----------------| +| | Same form, different industry | | | +| | Different form, same function | | | +| | Different form, different function, same objective | | | + +**Same form, different industry:** Products that look like yours but come from a different industry category. Example: For a digital learning platform, this includes physical textbooks and in-person courses. + +**Different form, same function:** Products that serve the same function in a different way. Example: For a project management tool, this includes spreadsheets and email. + +**Different form, different function, same objective:** Products that accomplish the same buyer objective through a completely different mechanism. Example: For a fitness app, this includes personal trainers, group classes, and home exercise DVDs. + +### Step 2: Choose the Price Level Within the Corridor + +Once you have mapped the corridor, choose where to price based on two factors: + +| Factor | Higher Price Within Corridor | Lower Price Within Corridor | +|--------|-----------------------------|-----------------------------| +| **Legal protection** | Strong IP/patent protection | Weak protection, easy to copy | +| **Network effects** | Strong network effects | No network effects | +| **Resource barrier** | Expensive to replicate (exclusive partnerships, infrastructure) | Low barrier to replication | +| **Switching costs** | High switching costs once adopted | Easy to switch away | + +**If you have strong protection:** Price toward the upper end of the corridor. You have time before competitors can match you. + +**If you have weak protection:** Price toward the lower end of the corridor. Make it economically unattractive for others to enter your blue ocean. + +### Step 3: Validate the Price + +| Validation Check | Pass? | +|-----------------|-------| +| Is the price within the corridor of the mass (not above it)? | | +| Would a non-customer be willing to pay this price for the utility offered? | | +| Does the price make alternatives seem like poor value by comparison? | | +| Is the price sustainable (not a loss-leader that requires future increases)? | | +| Can the target cost be achieved at this price (see Gate 3)? | | + +### Pricing Anti-Patterns + +| Anti-Pattern | Problem | Fix | +|-------------|---------|-----| +| Cost-plus pricing | Ignores buyer value and alternatives | Price against alternatives, then work backward to cost | +| Competitor-matching | Stays in the red ocean | Price against all alternatives, not just direct competitors | +| Premium for novelty | Limits adoption to early adopters | Price for the mass market from day one | +| Free/freemium by default | May signal low value, unsustainable | Free only if network effects or data value justify it | +| Anchor to existing price | Misses the mass if existing prices are too high | Map the full corridor including non-industry alternatives | + +## Gate 3: Target Cost + +### The Principle + +Target cost is derived from the strategic price, not the other way around. The formula is simple: + +``` +Strategic Price - Desired Profit Margin = Target Cost +``` + +If you cannot achieve the target cost, you do not raise the price. You redesign the offering to reduce cost. The ERRC grid is the primary tool for achieving target cost. + +### Three Levers for Achieving Target Cost + +#### Lever 1: Streamline Operations Through ERRC + +The first and most powerful lever. Every factor you eliminate or reduce directly lowers cost. + +| ERRC Action | Cost Impact | +|-------------|-------------| +| Factors eliminated | Direct cost removal (often the largest savings) | +| Factors reduced | Partial cost reduction | +| Factors raised | May increase cost (but funded by eliminate/reduce) | +| Factors created | May increase cost (but funded by eliminate/reduce) | + +**The math must work:** Total cost of raise + create must be less than total savings from eliminate + reduce. + +#### Lever 2: Partnering + +If you cannot achieve the target cost alone, partner with others who have the capabilities or scale you lack. + +**When to partner:** +- A capability you need would take years and significant investment to build +- A partner already has the capability at the cost level you need +- The partnership does not compromise the buyer utility + +**Examples:** +- Apple partnered with music labels for iTunes (content) +- Nespresso partnered with machine manufacturers (hardware) to focus on capsules +- IKEA partners with low-cost manufacturers globally + +#### Lever 3: Change the Pricing Model + +Sometimes the target cost cannot be achieved with a traditional purchase model. Changing the pricing model can align cost with buyer value. + +| Model | When to Use | Example | +|-------|-------------|---------| +| Subscription | High upfront cost, ongoing value | Netflix, Salesforce | +| Pay-per-use | Irregular usage patterns | Cloud computing (AWS), ride-hailing | +| Freemium | Network effects fund the model | Spotify, Zoom | +| Revenue share | Partner can fund upfront cost | JCDecaux (free shelters, ad revenue) | +| Leasing | High asset cost, ongoing need | Aircraft engines (Rolls-Royce power-by-the-hour) | + +### Target Cost Template + +``` +Strategic Price: $___________ +Desired Profit Margin: ___________% +Target Cost: $___________ + +Cost Breakdown: + Cost saved from Eliminate actions: $___________ + Cost saved from Reduce actions: $___________ + Cost added from Raise actions: $___________ + Cost added from Create actions: $___________ + Net ERRC impact: $___________ + + Partnership cost savings: $___________ + Pricing model adjustment: $___________ + +Achievable Cost: $___________ +Gap (Target - Achievable): $___________ + +If gap > 0: Revisit ERRC or pricing model +If gap <= 0: Proceed to Gate 4 +``` + +## Gate 4: Adoption Hurdles + +### The Principle + +Even a brilliant blue ocean strategy will fail if the organization cannot execute it or if key stakeholders resist. The final gate addresses four categories of adoption hurdles. + +### The Four Adoption Hurdles + +#### Hurdle 1: Employees + +**The challenge:** Internal teams may resist the new strategy because it changes their roles, threatens their expertise, or contradicts what they believe about the business. + +**Common resistance patterns:** +- "Our customers do not want this" (projecting existing customer needs onto non-customers) +- "We have always done it this way" (attachment to eliminated factors) +- "This devalues our expertise" (skills built around reduced/eliminated factors) + +**Mitigation strategies:** + +| Strategy | How | +|----------|-----| +| Involve early | Include key employees in ERRC workshops | +| Show the data | Share non-customer research that supports the shift | +| Pilot first | Start with a small team to prove the concept | +| Retrain | Invest in developing skills for the new factors | +| Celebrate converts | Publicly recognize employees who embrace the shift | + +#### Hurdle 2: Business Partners + +**The challenge:** Distributors, suppliers, and channel partners may resist because the new strategy disrupts their business model or reduces their value. + +**Mitigation strategies:** + +| Strategy | How | +|----------|-----| +| Co-create value | Show partners how the blue ocean expands the total pie | +| Pilot with willing partners | Find one or two forward-thinking partners to prove the model | +| Provide transition support | Help partners adapt their business to the new model | +| Create new partnerships | If existing partners cannot adapt, find new ones | + +#### Hurdle 3: The General Public + +**The challenge:** The public (including potential buyers) may not understand the new offering or may be skeptical of unfamiliar categories. + +**Mitigation strategies:** + +| Strategy | How | +|----------|-----| +| Demonstrate, do not explain | Let people experience the offering (free trials, demos) | +| Leverage word-of-mouth | Design the experience to be naturally shareable | +| Use familiar reference points | "Like X but with Y" framing | +| Start with early believers | Find the community most likely to embrace the new category | + +#### Hurdle 4: Regulators and Legal + +**The challenge:** New categories often fall outside existing regulatory frameworks, creating uncertainty or opposition. + +**Mitigation strategies:** + +| Strategy | How | +|----------|-----| +| Engage proactively | Meet with regulators before launch, not after conflict | +| Frame as public benefit | Show how the blue ocean serves public interest | +| Self-regulate | Establish industry standards before regulators impose them | +| Pilot in friendly jurisdictions | Launch in markets with favorable regulatory environments | + +### Adoption Hurdle Assessment Template + +For each stakeholder group, rate the risk (1-5) and document the mitigation plan. + +| Stakeholder | Risk Level (1-5) | Key Concern | Mitigation Plan | Owner | Timeline | +|-------------|-------------------|-------------|-----------------|-------|----------| +| Employees | | | | | | +| Partners | | | | | | +| Public/Buyers | | | | | | +| Regulators | | | | | | + +## Sequence Validation Checklist + +Before committing to a blue ocean strategy, verify that it passes all four gates. + +### Gate 1: Buyer Utility + +- [ ] The Buyer Utility Map identifies specific cells with a leap in utility +- [ ] The utility leap is obvious to a first-time buyer without explanation +- [ ] Non-customers confirm the offering would address their primary barrier +- [ ] The utility is differentiated from all alternatives, not just direct competitors + +### Gate 2: Strategic Price + +- [ ] Alternatives from multiple industries have been mapped +- [ ] The price corridor of the mass has been identified +- [ ] The chosen price attracts non-customers, not just existing customers +- [ ] The price level reflects the degree of legal/competitive protection +- [ ] The price makes alternatives seem like poor value by comparison + +### Gate 3: Target Cost + +- [ ] Target cost is derived from strategic price minus desired margin +- [ ] ERRC elimination and reduction generate sufficient cost savings +- [ ] The math works: raise + create costs are less than eliminate + reduce savings +- [ ] Partnership opportunities have been explored for cost gaps +- [ ] Alternative pricing models have been considered if needed +- [ ] Target cost is achievable from day one (not "after we scale") + +### Gate 4: Adoption + +- [ ] Employee resistance has been assessed and mitigation planned +- [ ] Partner impact has been evaluated and addressed +- [ ] Public/buyer education strategy is in place +- [ ] Regulatory risks have been identified and proactively addressed +- [ ] A pilot plan exists to validate before full rollout +- [ ] Fair process (engagement, explanation, expectation clarity) is being used + +## Common Sequencing Mistakes + +### Mistake 1: Starting with Cost Instead of Utility + +Companies often begin by asking "What can we afford to build?" instead of "What utility leap would unlock new demand?" This produces cost-efficient but uninspiring offerings that stay in the red ocean. + +**Fix:** Always start with the Buyer Utility Map. Define the utility leap first, then figure out how to achieve it at the right cost. + +### Mistake 2: Pricing Based on Cost-Plus + +Adding a margin to the production cost ignores buyer alternatives and often results in a price that is either too high (limiting adoption) or too low (leaving value on the table). + +**Fix:** Map all alternatives. Set price within the corridor of the mass. Work backward to the cost target. + +### Mistake 3: Assuming Scale Will Solve the Cost Problem + +"We will be expensive at first but costs will come down with scale" is a dangerous assumption. If costs are too high at launch, adoption will be too slow to achieve the scale needed to reduce costs. + +**Fix:** Achieve target cost at launch volume, not projected future volume. Use ERRC and partnerships to bridge the gap. + +### Mistake 4: Ignoring Adoption Until Launch + +Discovering that employees, partners, or regulators resist the strategy at launch is too late. Adoption hurdles must be addressed during strategy development, not after. + +**Fix:** Assess adoption hurdles early. Include key stakeholders in the strategy development process. Use fair process throughout. + +### Mistake 5: Skipping Gates + +Each gate is a checkpoint. Proceeding to pricing without confirming buyer utility, or to cost without confirming price, creates compounding errors that surface late and expensively. + +**Fix:** Treat each gate as a formal review. Do not proceed until the gate criteria are met. It is better to rework earlier than to discover a fatal flaw later. diff --git a/.agents/skills/blue-ocean-strategy/references/six-paths.md b/.agents/skills/blue-ocean-strategy/references/six-paths.md new file mode 100644 index 00000000..26d215fc --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/references/six-paths.md @@ -0,0 +1,471 @@ +# The Six Paths Framework + +The Six Paths Framework provides six systematic ways to look beyond the conventional boundaries of an industry and discover blue ocean opportunities. Most companies define their competitive landscape narrowly: same industry, same strategic group, same buyer, same scope of product, same appeal, same point in time. Each path challenges one of these boundaries. This reference provides detailed exercises and real-world examples for each path. + + +## Table of Contents +1. [Overview of the Six Paths](#overview-of-the-six-paths) +2. [Path 1: Look Across Alternative Industries](#path-1-look-across-alternative-industries) +3. [Path 2: Look Across Strategic Groups](#path-2-look-across-strategic-groups) +4. [Path 3: Look Across the Chain of Buyers](#path-3-look-across-the-chain-of-buyers) +5. [Path 4: Look Across Complementary Products and Services](#path-4-look-across-complementary-products-and-services) +6. [Path 5: Look Across Functional or Emotional Appeal](#path-5-look-across-functional-or-emotional-appeal) +7. [Path 6: Look Across Time](#path-6-look-across-time) +8. [Workshop Format: Exploring All Six Paths](#workshop-format-exploring-all-six-paths) + +--- + +## Overview of the Six Paths + +| Path | Boundary Challenged | Core Question | +|------|---------------------|---------------| +| 1. Alternative Industries | Industry definition | What alternatives do buyers choose between? | +| 2. Strategic Groups | Strategic positioning | What if you bridged two strategic groups? | +| 3. Chain of Buyers | Buyer definition | Who else in the buyer chain can you target? | +| 4. Complementary Products | Scope of offering | What happens before, during, and after use? | +| 5. Functional-Emotional Appeal | Industry orientation | Can you switch the appeal type? | +| 6. Time/Trends | Time horizon | What trends will reshape buyer needs? | + +Each path is independent. You do not need to explore all six. Often, one or two paths will yield the most promising blue ocean opportunities for your specific situation. However, exploring all six ensures you do not miss a breakthrough hiding in an unexpected direction. + +## Path 1: Look Across Alternative Industries + +### The Insight + +Industries are narrowly defined by convention. But buyers choose between alternatives that cross industry lines. A person deciding how to spend a Friday evening chooses between restaurants, movies, concerts, and staying home with streaming. These are all alternatives serving the same job: "enjoyable evening out (or in)." + +### Real-World Examples + +| Company | Alternatives Bridged | Blue Ocean Created | +|---------|----------------------|-------------------| +| NetJets | Commercial first class vs. owning a private jet | Fractional jet ownership: luxury of private flying at fraction of ownership cost | +| Intuit QuickBooks | Hiring an accountant vs. manual bookkeeping | Simple software that replaces both for small businesses | +| Home Depot | Hiring a contractor vs. doing nothing | DIY with expert advice and all supplies in one location | +| Salesforce (early) | Enterprise CRM software vs. spreadsheets | Web-based CRM accessible to SMBs who could not afford or implement enterprise solutions | + +### Exercise Template: Alternative Industries Analysis + +**Step 1:** Define the fundamental job your buyer is trying to accomplish. + +``` +Our buyer's core job-to-be-done: _________________________________ +``` + +**Step 2:** List all the ways buyers currently accomplish this job, including options outside your industry. + +| Alternative | Industry | Key Advantages | Key Disadvantages | +|-------------|----------|----------------|-------------------| +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | + +**Step 3:** For each alternative, identify what it does better than your industry. + +**Step 4:** Ask: What if we combined the best elements of multiple alternatives into one offering? + +**Step 5:** Draft an ERRC grid based on cross-alternative insights. + +``` +Eliminate (from our industry): ___________________________________ +Reduce (below our industry norm): ________________________________ +Raise (above our industry norm, borrowed from alternatives): ______ +Create (new, combining alternative strengths): ____________________ +``` + +### Key Questions for Path 1 + +- Why do buyers switch between your industry and alternatives? +- What triggers a buyer to choose an alternative over your industry? +- What would make someone who currently uses an alternative consider your industry? +- What does the alternative offer that your industry does not? + +--- + +## Path 2: Look Across Strategic Groups + +### The Insight + +Within every industry, companies cluster into strategic groups based on similar price/performance combinations. Luxury vs. economy. Full-service vs. self-service. Enterprise vs. SMB. Most companies compete within their group. Blue ocean opportunities emerge at the boundary between groups. + +### Real-World Examples + +| Company | Groups Bridged | Blue Ocean Created | +|---------|---------------|-------------------| +| Lexus | Luxury (Mercedes, BMW) and mass-market | Luxury quality at accessible pricing | +| Trader Joe's | Gourmet specialty stores and discount grocers | Affordable gourmet: unique, high-quality products at low prices in a fun environment | +| Toyota Camry | Economy cars and mid-range cars | Reliable, well-equipped car at economy price point | +| Warby Parker | Designer eyewear ($300+) and budget eyewear ($50) | Stylish, quality frames at $95 with home try-on | + +### Exercise Template: Strategic Group Mapping + +**Step 1:** Identify the strategic groups in your industry. + +Map groups on two axes: Price (low to high) and a key performance dimension. + +``` + HIGH PERFORMANCE + | + Group C | Group A + (Niche premium) | (Full premium) + | + LOW PRICE ————————————+———————————— HIGH PRICE + | + Group D | Group B + (Basic/budget) | (Mid-range) + | + LOW PERFORMANCE +``` + +**Step 2:** For each group, list what they emphasize and what they sacrifice. + +| Strategic Group | Emphasizes | Sacrifices | +|----------------|------------|------------| +| Group A | | | +| Group B | | | +| Group C | | | +| Group D | | | + +**Step 3:** Identify the gap between groups. + +- What would it take to deliver Group A's key advantage at Group B's price point? +- What does Group D sacrifice that a hybrid could restore? +- Where is there a "white space" between groups that no one occupies? + +**Step 4:** Design a cross-group offering. + +``` +We will offer [Group ___]'s _____________ at [Group ___]'s _____________. +This is possible because we will eliminate: _________________________ +And reduce: _____________________________________________________ +``` + +### Key Questions for Path 2 + +- Why do buyers trade up to a higher strategic group? What triggers it? +- Why do buyers trade down to a lower strategic group? What makes them willing to sacrifice? +- Can you deliver the most valued elements of the higher group at the cost structure of the lower group? +- Is there a group that does not yet exist but logically should? + +--- + +## Path 3: Look Across the Chain of Buyers + +### The Insight + +Most industries converge on a single buyer group out of habit. But the purchase chain typically includes multiple distinct roles: purchasers (who pay), users (who use), and influencers (who shape the decision). Shifting focus to a different buyer in the chain can unlock new value. + +### Real-World Examples + +| Company | Traditional Buyer | Shifted To | Blue Ocean Created | +|---------|-------------------|------------|-------------------| +| Bloomberg Terminal | IT departments (purchasers) | Traders (users) | Terminals with real-time analytics designed for traders, who then demanded them from IT | +| Novo Nordisk NovoPen | Pharmacies (purchasers) | Patients (users) | Insulin pen that patients loved using, pulling demand through the chain | +| SAP early days | IT departments (purchasers) | CFOs (influencers) | Sold business value to finance leaders who then mandated adoption | +| Salesforce | IT departments (purchasers) | Sales reps (users) | Self-service CRM that sales reps adopted from the bottom up | + +### Exercise Template: Buyer Chain Analysis + +**Step 1:** Map the complete buyer chain for your industry. + +``` +INFLUENCERS PURCHASERS USERS +(Who shapes the (Who pays/approves (Who uses the +decision?) the purchase?) product/service?) + +1. ________________ 1. ________________ 1. ________________ +2. ________________ 2. ________________ 2. ________________ +3. ________________ 3. ________________ 3. ________________ +``` + +**Step 2:** Identify which buyer your industry currently targets. + +``` +Our industry predominantly targets: [ ] Influencers [ ] Purchasers [ ] Users +``` + +**Step 3:** Explore the unmet needs of overlooked buyers. + +| Buyer Role | Currently Targeted? | Top Unmet Needs | What They Value Most | +|------------|--------------------|-----------------|--------------------| +| Influencer | | | | +| Purchaser | | | | +| User | | | | + +**Step 4:** Design a shift. + +``` +We will shift focus from _____________ to _____________. +Their key unmet need is: ________________________________________ +We will serve this need by: _____________________________________ +This is viable because: _________________________________________ +``` + +### Key Questions for Path 3 + +- Who in the chain has the most frustration with the current offering? +- Who in the chain has the most influence but the least attention from the industry? +- What would happen if you designed the entire offering around a different buyer in the chain? +- Can you bypass one buyer entirely and go direct to another? + +--- + +## Path 4: Look Across Complementary Products and Services + +### The Insight + +Products and services are rarely used in isolation. There is a broader context: what happens before, during, and after use. Pain points in complementary activities represent blue ocean opportunities if you can bundle solutions. + +### Real-World Examples + +| Company | Core Product | Complementary Pain Addressed | Blue Ocean Created | +|---------|-------------|-----------------------------|--------------------| +| Apple (iPod + iTunes) | Music player | Legal music acquisition was painful | Seamless hardware + software + content ecosystem | +| IKEA | Furniture | Childcare while shopping, eating during long shopping trips | In-store restaurants and childcare | +| Peloton | Exercise bike | Going to gym is time-consuming, classes have fixed schedules | At-home bike with live/on-demand classes | +| Nespresso | Coffee machine | Grinding beans, measuring, cleaning is tedious | Single-pod system eliminating all preparation friction | + +### Exercise Template: Experience Mapping + +**Step 1:** Map the complete buyer experience across all stages. + +| Stage | What Buyer Does | Pain Points | Time Spent | Emotional State | +|-------|----------------|-------------|------------|-----------------| +| **Before purchase** | Research, compare, get approval | | | | +| **Purchase** | Order, pay, arrange delivery | | | | +| **Delivery/Setup** | Receive, install, configure | | | | +| **Core use** | Daily/regular use of the product | | | | +| **Complementary activities** | What they need alongside use | | | | +| **Maintenance** | Updates, repairs, renewals | | | | +| **Disposal/Replacement** | End-of-life, switching | | | | + +**Step 2:** Identify the biggest pain points outside the core use stage. + +**Step 3:** Ask: Which of these pain points could we solve by expanding our offering? + +``` +Pain point: ____________________________________________________ +Current workaround: ____________________________________________ +Our potential solution: _________________________________________ +Cost to include: _______________________________________________ +Value to buyer: ________________________________________________ +``` + +**Step 4:** Design the bundled offering. + +### Key Questions for Path 4 + +- What do buyers need to do before they can use your product? +- What are the biggest frustrations during the total experience, not just the core use? +- What complementary products do buyers always purchase alongside yours? +- What if you bundled the complement into your core offering? +- Where do buyers waste time in activities surrounding your product? + +--- + +## Path 5: Look Across Functional or Emotional Appeal + +### The Insight + +Some industries compete primarily on function: price, features, specifications, performance metrics. Others compete primarily on emotion: brand image, feelings, status, aesthetics. Industries rarely compete on both. Shifting the orientation can create a blue ocean. + +### Real-World Examples + +**Functional to Emotional:** + +| Company | Industry Norm (Functional) | Emotional Shift | Blue Ocean Created | +|---------|---------------------------|-----------------|-------------------| +| Swatch | Watches as precise timekeeping instruments | Watches as fashion accessories and self-expression | Affordable, collectible, fashion-forward watches | +| Starbucks | Coffee as a commodity caffeine delivery | Coffee as a "third place" experience | Premium coffee experience with ambiance and identity | +| Apple | Computers as functional tools (specs, processing power) | Computers as lifestyle and creativity expression | Design-centric products people love to own | + +**Emotional to Functional:** + +| Company | Industry Norm (Emotional) | Functional Shift | Blue Ocean Created | +|---------|--------------------------|-------------------|-------------------| +| The Body Shop | Cosmetics sold on beauty, glamour, youth | Cosmetics sold on natural ingredients, ethical sourcing | Values-based beauty brand | +| CEMEX | Cement sold on brand/relationship in developing markets | Cement sold on enabling homebuilding with financing and support | Complete home-building solution for low-income families | +| Dollar Shave Club | Razors marketed with sports celebrities and masculinity | Razors as simple, functional, affordable commodity | Subscription convenience without the brand tax | + +### Exercise Template: Appeal Analysis + +**Step 1:** Determine your industry's current orientation. + +``` +Our industry competes primarily on: +[ ] Functional factors (price, specs, features, performance) +[ ] Emotional factors (brand, image, feelings, status, experience) +[ ] Mixed (roughly balanced) +``` + +**Step 2:** List the current competing factors by type. + +| Functional Factors | Current Investment (1-5) | Emotional Factors | Current Investment (1-5) | +|-------------------|------------------------|-------------------|------------------------| +| | | | | +| | | | | +| | | | | +| | | | | + +**Step 3:** Explore the opposite dimension. + +If your industry is functional, ask: +- What emotional elements could we add that would differentiate us? +- How do buyers feel when using our product? What would they prefer to feel? +- What identity or status could our offering confer? +- What experience could we create around the functional product? + +If your industry is emotional, ask: +- What functional benefits are hidden under the emotional branding? +- What would happen if we stripped away the emotional premium and offered pure function at lower cost? +- Which emotional factors drive cost but not purchase decisions? +- What if we made the buying process radically transparent and functional? + +**Step 4:** Design the cross-appeal offering. + +``` +We will shift from [functional/emotional] to [emotional/functional] by: +Eliminating: ___________________________________________________ +Creating: ______________________________________________________ +The buyer benefit: ______________________________________________ +``` + +### Key Questions for Path 5 + +- Is your industry over-invested in functional OR emotional factors? +- What would it look like to be the most functional player in an emotional industry? +- What would it look like to be the most emotional player in a functional industry? +- Which emotional factors are buyers paying for but not truly valuing? +- Which functional needs are unmet because the industry focuses on emotions? + +--- + +## Path 6: Look Across Time + +### The Insight + +Industries are shaped by external trends, but most companies adapt to trends reactively and incrementally. Blue ocean creators identify decisive trends early and build offerings that align with where the market is going, not where it is today. + +### Real-World Examples + +| Company | Trend Identified | Blue Ocean Created | +|---------|-----------------|-------------------| +| Apple iTunes | Digital music consumption was inevitable (post-Napster) | Legal digital music platform before the industry was ready | +| Tesla | Electric vehicles would become mainstream (environmental regulation + battery cost decline) | Premium EV brand positioned before mass adoption | +| Airbnb | Peer-to-peer economy + mobile-first travel booking | Home-sharing platform leveraging underutilized residential capacity | +| Zoom | Remote work was growing steadily (pre-pandemic) | Frictionless video conferencing for the distributed workforce era | + +### Exercise Template: Trend Analysis + +**Step 1:** Identify trends that are relevant to your industry. + +Evaluate each trend against three criteria (from Kim and Mauborgne): + +| Trend | Decisive to Industry? | Irreversible? | Has Clear Trajectory? | All Three = Yes? | +|-------|----------------------|---------------|----------------------|-------------------| +| | | | | | +| | | | | | +| | | | | | +| | | | | | +| | | | | | + +A trend is actionable for blue ocean strategy only if it is decisive to the industry, irreversible, and has a clear trajectory. Speculative or reversible trends are too risky to build strategy around. + +**Step 2:** For each qualifying trend, project the impact. + +``` +Trend: _________________________________________________________ +Current state: _________________________________________________ +Projected state in 3-5 years: __________________________________ +Impact on buyer behavior: ______________________________________ +Impact on cost structure: ______________________________________ +Impact on industry boundaries: _________________________________ +``` + +**Step 3:** Identify the blue ocean opportunity. + +``` +If [trend] continues, buyers will need: ________________________ +Currently, the industry offers: ________________________________ +The gap between future need and current offering: _______________ +We can fill this gap by: _______________________________________ +``` + +**Step 4:** Design the trend-forward offering using ERRC. + +| Eliminate (irrelevant in the future) | Raise (more important in the future) | +|--------------------------------------|--------------------------------------| +| | | +| | | + +| Reduce (less important in the future) | Create (new need driven by the trend) | +|---------------------------------------|---------------------------------------| +| | | +| | | + +### Key Questions for Path 6 + +- What trends are irreversibly changing buyer behavior in your industry? +- What will your buyers need in 3-5 years that they do not need today? +- What current industry factors will become irrelevant as trends play out? +- Can you build for the future state now, before competitors react? +- What would a company founded 5 years from now look like? + +--- + +## Workshop Format: Exploring All Six Paths + +### Full-Day Workshop (6 hours) + +This workshop systematically explores all six paths with a cross-functional team. + +**Preparation:** +- Completed strategy canvas (current state) +- Customer and non-customer interview data +- Industry trend reports +- 8-12 cross-functional participants + +**Agenda:** + +| Time | Activity | Path | +|------|----------|------| +| 0:00-0:15 | Welcome, review strategy canvas, set objectives | - | +| 0:15-0:55 | Path 1: Alternative Industries (exercise + discussion) | 1 | +| 0:55-1:35 | Path 2: Strategic Groups (exercise + discussion) | 2 | +| 1:35-2:15 | Path 3: Chain of Buyers (exercise + discussion) | 3 | +| 2:15-2:45 | Lunch break | - | +| 2:45-3:25 | Path 4: Complementary Products (exercise + discussion) | 4 | +| 3:25-4:05 | Path 5: Functional-Emotional Appeal (exercise + discussion) | 5 | +| 4:05-4:45 | Path 6: Time/Trends (exercise + discussion) | 6 | +| 4:45-5:00 | Break | - | +| 5:00-5:30 | Synthesis: Which paths revealed the strongest opportunities? | All | +| 5:30-6:00 | Prioritize top 3 opportunities, assign next steps | All | + +**Facilitation tips:** +- Spend no more than 40 minutes per path (10 min intro, 15 min exercise, 15 min discussion) +- Use a "parking lot" for ideas that come up outside the current path +- Have participants vote on the most promising insight from each path before moving on +- The synthesis session is the most important part: look for convergence across paths +- Assign one person to document all outputs in real time + +### Half-Day Express Version (3 hours) + +If time is limited, focus on the three paths most likely to yield results for your specific situation. + +**How to choose which three paths:** +- If you are in a commodity market: Paths 1, 5, 4 +- If you are in a complex B2B market: Paths 3, 4, 6 +- If you are in a consumer market: Paths 1, 2, 5 +- If you are in a rapidly changing market: Paths 6, 1, 4 + +### Output Checklist + +After the workshop, you should have: + +- [ ] At least 2-3 blue ocean opportunity ideas per path explored +- [ ] A ranked list of the top 5 opportunities across all paths +- [ ] For each top opportunity: a preliminary ERRC grid +- [ ] Assigned owners and timelines for deeper investigation +- [ ] Identified data gaps that need to be filled before decisions +- [ ] A plan for non-customer interviews to validate top opportunities diff --git a/.agents/skills/blue-ocean-strategy/references/strategy-canvas.md b/.agents/skills/blue-ocean-strategy/references/strategy-canvas.md new file mode 100644 index 00000000..26732051 --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/references/strategy-canvas.md @@ -0,0 +1,388 @@ +# Strategy Canvas + +The strategy canvas is the central diagnostic and action framework of blue ocean strategy. It captures the current state of play in an industry, shows where competitors invest, and reveals opportunities to create new market space. This reference provides step-by-step instructions for creating, reading, and using strategy canvases. + + +## Table of Contents +1. [What a Strategy Canvas Shows](#what-a-strategy-canvas-shows) +2. [Step-by-Step: Creating a Strategy Canvas](#step-by-step-creating-a-strategy-canvas) +3. [Reading the Canvas: What Curve Shapes Mean](#reading-the-canvas-what-curve-shapes-mean) +4. [Strategy Canvas Templates for Common Industries](#strategy-canvas-templates-for-common-industries) +5. [Before/After Strategy Canvas Examples](#beforeafter-strategy-canvas-examples) +6. [Common Mistakes When Creating Strategy Canvases](#common-mistakes-when-creating-strategy-canvases) +7. [Using the Strategy Canvas in Team Workshops](#using-the-strategy-canvas-in-team-workshops) +8. [Digital Tools for Strategy Canvas Creation](#digital-tools-for-strategy-canvas-creation) +9. [Strategy Canvas Checklist](#strategy-canvas-checklist) + +--- + +## What a Strategy Canvas Shows + +A strategy canvas is a one-page visual that plots: + +- **Horizontal axis:** The key competing factors the industry invests in and competes on +- **Vertical axis:** The offering level buyers receive across each factor (low to high) +- **Value curves:** Lines connecting the dots for each competitor or strategic group + +When all competitors' value curves have the same shape, the industry is a red ocean. When a company's curve is fundamentally different, it has found (or created) a blue ocean. + +## Step-by-Step: Creating a Strategy Canvas + +### Step 1: Define the Industry Scope + +Before listing factors, clarify what industry or category you are mapping. Be specific. + +**Good scope definitions:** +- "Mid-range casual dining restaurants in the U.S." +- "B2B project management software for teams of 10-50" +- "Personal fitness solutions for women aged 30-50" + +**Poor scope definitions:** +- "Food industry" (too broad) +- "Software" (too broad) +- "Our direct competitor" (too narrow) + +### Step 2: Identify Competing Factors + +List every factor the industry competes on and that buyers use to make decisions. Include both explicit (price, features) and implicit (brand prestige, emotional appeal) factors. + +**Methods for identifying factors:** + +| Method | How | What It Reveals | +|--------|-----|-----------------| +| Competitor analysis | Study marketing materials, pricing, features of top 5-8 players | What the industry thinks matters | +| Customer interviews | Ask 10-15 customers what they consider when buying | What buyers actually evaluate | +| Review mining | Analyze 100+ reviews for recurring themes | What drives satisfaction and complaints | +| Sales team input | Ask sales reps what objections and comparisons they hear | What factors influence purchase decisions | +| Industry reports | Read analyst reports and trade publications | What metrics the industry tracks | + +**Aim for 8-14 factors.** Fewer than 8 may miss important dimensions. More than 14 becomes unwieldy. + +### Step 3: List and Order the Factors + +Arrange factors on the horizontal axis in a logical order. Common orderings: + +- **By category:** Price factors, product factors, service factors, brand factors +- **By buyer journey:** Discovery, evaluation, purchase, use, support +- **By importance:** Most to least important (based on customer research) + +### Step 4: Rate Each Player + +For each competitor (or strategic group), rate the offering level on each factor as Low, Medium-Low, Medium, Medium-High, or High. Use a 1-5 scale. + +**Rating guidelines:** + +| Rating | Meaning | +|--------|---------| +| 1 (Low) | Minimal or no investment in this factor | +| 2 (Medium-Low) | Below industry average | +| 3 (Medium) | Industry average | +| 4 (Medium-High) | Above industry average | +| 5 (High) | Industry-leading investment in this factor | + +**Important:** Rate based on the actual offering level, not what the company claims. Use customer perception, not internal metrics. + +### Step 5: Plot the Canvas + +Draw the canvas with factors on the x-axis and offering levels (1-5) on the y-axis. Connect each player's dots to form their value curve. + +**Text-based format for digital collaboration:** + +``` +Factor | Player A | Player B | Player C | Blue Ocean +--------------------|----------|----------|----------|---------- +Price | 3 | 4 | 2 | 4 +Feature depth | 4 | 3 | 5 | 1 +Ease of use | 2 | 2 | 2 | 5 +Customer support | 3 | 4 | 3 | 2 +Customization | 4 | 3 | 5 | 1 +Speed to value | 1 | 2 | 1 | 5 +Community | 1 | 1 | 2 | 5 +Integration breadth | 4 | 3 | 4 | 2 +``` + +### Step 6: Analyze the Canvas + +Look for these patterns in the current state. + +## Reading the Canvas: What Curve Shapes Mean + +### Convergent Curves (Red Ocean Signal) + +When all competitors' curves roughly overlap, the industry is in a red ocean. Companies are competing on the same factors at similar levels. This is the most common pattern and the biggest opportunity for blue ocean creation. + +**What to do:** Apply the ERRC grid aggressively. The convergence means the industry has defined "good" narrowly, leaving room for a divergent approach. + +### The "More for More" Curve + +One player scores high on every factor, at a premium price. This is a differentiation strategy, not value innovation. It is expensive to sustain and vulnerable to a blue ocean entrant who eliminates the factors that do not matter. + +**What to do:** Ask which of those "high" factors buyers would willingly trade away for something new. + +### The Zigzag Curve + +A player scores high on some factors and low on others without a clear strategic logic. This usually indicates an unfocused strategy driven by reactive decisions. + +**What to do:** Identify whether the highs and lows reflect a coherent buyer need. If not, the company is vulnerable. + +### The Divergent Curve (Blue Ocean Signal) + +One player's curve has a fundamentally different shape: low where others are high, high where others are low, and peaks on factors others do not even have. This is the signature of a blue ocean strategy. + +**Characteristics of a strong divergent curve:** +- **Focus:** High on only 3-4 factors (not trying to be good at everything) +- **Divergence:** Clear difference from industry norm +- **Compelling tagline:** The strategy can be summarized in one memorable phrase + +## Strategy Canvas Templates for Common Industries + +### SaaS / Software + +Typical competing factors: +- Price / Total cost of ownership +- Feature depth +- Ease of use / Time to value +- Customization / Configuration +- Integration ecosystem +- Customer support quality +- Security / Compliance +- Brand / Market reputation +- Scalability +- Mobile experience + +### Retail / E-Commerce + +Typical competing factors: +- Price +- Product selection breadth +- Product quality +- Shopping experience +- Delivery speed +- Return policy +- Customer service +- Brand prestige +- Loyalty program +- Store / Website design + +### Professional Services + +Typical competing factors: +- Hourly / Project rate +- Expertise depth +- Team size +- Industry specialization +- Response time +- Deliverable quality +- Relationship / Account management +- Geographic presence +- Technology tools +- Brand reputation + +### Healthcare / Wellness + +Typical competing factors: +- Cost to patient +- Wait time +- Clinical outcomes +- Patient experience +- Accessibility (locations, hours) +- Technology (telehealth, apps) +- Specialization depth +- Insurance acceptance +- Preventive care focus +- Follow-up / Continuity + +## Before/After Strategy Canvas Examples + +### Example: Budget Hotel Industry + +**Before (Red Ocean):** + +``` +Factor | Economy Hotels | Mid-Range Hotels | Motels +--------------------|----------------|------------------|-------- +Price | 4 | 2 | 5 +Room quality | 2 | 4 | 1 +Restaurant | 1 | 4 | 1 +Lobby aesthetics | 1 | 4 | 1 +Room size | 2 | 4 | 2 +Front desk service | 3 | 4 | 2 +Amenities (pool) | 1 | 4 | 1 +Bed quality | 2 | 3 | 1 +Hygiene | 3 | 4 | 2 +Quietness | 2 | 3 | 2 +``` + +**After (Blue Ocean: Formule 1 / citizenM-style):** + +``` +Factor | Industry Avg | Blue Ocean Hotel +--------------------|--------------|------------------ +Price | 3 | 4 +Room quality | 2 | 2 +Restaurant | 2 | 1 +Lobby aesthetics | 2 | 5 +Room size | 3 | 1 +Front desk service | 3 | 1 +Amenities (pool) | 2 | 1 +Bed quality | 2 | 5 +Hygiene | 3 | 5 +Quietness | 2 | 5 +Self-service tech | 1 | 5 +Design / Instagram | 1 | 5 +``` + +**What changed:** Eliminated full-service expectations (restaurant, front desk, room size). Raised the factors that actually matter to tired travelers (bed quality, hygiene, quietness). Created new factors (self-service tech, design-forward spaces). + +### Example: Online Education + +**Before (Red Ocean):** + +``` +Factor | Traditional LMS | MOOC Platforms | Bootcamps +--------------------|-----------------|----------------|---------- +Price | 1 | 5 | 2 +Content depth | 4 | 4 | 3 +Certification value | 4 | 2 | 3 +Interactivity | 2 | 1 | 4 +Career outcomes | 3 | 1 | 4 +Self-paced | 3 | 5 | 1 +Community | 1 | 1 | 4 +Instructor access | 3 | 1 | 4 +Content freshness | 2 | 3 | 4 +``` + +**After (Blue Ocean: Cohort-Based Course):** + +``` +Factor | Industry Avg | Cohort-Based Course +--------------------|--------------|--------------------- +Price | 3 | 2 +Content depth | 4 | 2 +Certification value | 3 | 1 +Interactivity | 2 | 5 +Career outcomes | 3 | 5 +Self-paced | 3 | 1 +Community | 2 | 5 +Instructor access | 3 | 5 +Content freshness | 3 | 5 +Accountability | 1 | 5 +Peer network | 1 | 5 +``` + +**What changed:** Eliminated self-pacing and certification (factors with low buyer impact). Created accountability and peer networking (factors that drive actual learning outcomes). + +## Common Mistakes When Creating Strategy Canvases + +### Mistake 1: Using Internal Metrics Instead of Buyer Perception + +Companies often rate themselves based on what they know internally ("We have 500 features!") rather than how buyers perceive the offering. Always rate from the buyer's perspective. + +**Fix:** Validate ratings with customer interviews or surveys. If customers rate your "feature depth" as medium despite having 500 features, your canvas should say medium. + +### Mistake 2: Too Many Factors + +Including 20+ factors makes the canvas unreadable and dilutes strategic insight. The goal is to capture the factors that drive competitive dynamics and buying decisions. + +**Fix:** Limit to 8-14 factors. Combine related factors. Eliminate factors that do not influence buyer choice. + +### Mistake 3: Missing Implicit Factors + +Industries compete on factors that are never explicitly discussed: emotional safety, social signaling, ease of switching, time investment. These implicit factors often hold the key to blue ocean opportunities. + +**Fix:** Include at least 2-3 implicit/emotional factors alongside functional ones. + +### Mistake 4: Rating Everything as "Medium" + +When in doubt, teams default to rating everything as 3 out of 5. This produces flat, uninformative curves that obscure real strategic differences. + +**Fix:** Force-rank: at least 2 factors must be rated 1-2 and at least 2 must be rated 4-5 for each player. + +### Mistake 5: Drawing the Desired State Without ERRC Discipline + +Teams jump to "raise everything and create new factors" without eliminating or reducing anything. This produces a "more for more" curve that is not value innovation. + +**Fix:** Enforce the rule: for every factor you raise or create, you must eliminate or reduce at least one factor. + +### Mistake 6: Confusing Strategy Groups with Individual Companies + +In industries with many players, mapping every individual company creates noise. Group similar competitors into strategic groups and map the group average. + +**Fix:** Identify 3-5 strategic groups (e.g., "premium players," "value players," "niche specialists") and draw one curve per group. + +## Using the Strategy Canvas in Team Workshops + +### Workshop Format: Strategy Canvas Creation (3 hours) + +**Participants:** 6-12 people from cross-functional teams (product, sales, marketing, operations, customer success) + +**Materials:** Whiteboard or digital canvas tool, sticky notes, marker pens + +**Agenda:** + +| Time | Activity | Output | +|------|----------|--------| +| 0:00-0:20 | Introduction to strategy canvas concept | Shared understanding | +| 0:20-0:50 | Brainstorm competing factors (individual then group) | Factor list (15-20 items) | +| 0:50-1:10 | Prioritize and consolidate to 10-12 factors | Final factor list | +| 1:10-1:30 | Break | - | +| 1:30-2:00 | Rate competitors on each factor (silent voting then discussion) | Competitor ratings | +| 2:00-2:20 | Rate your own company (silent voting then discussion) | Self-assessment ratings | +| 2:20-2:40 | Draw the canvas and analyze patterns | Current-state canvas | +| 2:40-3:00 | Identify blue ocean opportunities (divergence brainstorm) | Opportunity shortlist | + +**Facilitation tips:** +- Use silent individual brainstorming before group discussion to avoid groupthink +- When rating, have each person write their rating on a sticky note and reveal simultaneously +- If there is wide disagreement on a rating, discuss and use the customer-facing team's perspective as tiebreaker +- Photograph or digitize the canvas immediately after the session + +### Follow-Up: From Canvas to Action (2 hours, 1 week later) + +| Time | Activity | Output | +|------|----------|--------| +| 0:00-0:15 | Review current-state canvas | Alignment | +| 0:15-0:45 | Apply ERRC: What to eliminate, reduce, raise, create? | ERRC grid | +| 0:45-1:15 | Draw the proposed blue ocean value curve | Target-state canvas | +| 1:15-1:45 | Stress-test: Would non-customers buy this? Can we achieve the cost? | Validation notes | +| 1:45-2:00 | Define next steps and owner for each ERRC action | Action plan | + +## Digital Tools for Strategy Canvas Creation + +| Tool | Best For | Cost | +|------|----------|------| +| Miro / FigJam | Collaborative workshops, remote teams | Free tier available | +| Google Sheets | Simple data entry and chart generation | Free | +| PowerPoint / Keynote | Polished presentations of final canvas | Included with office suites | +| Canvanizer | Dedicated strategy canvas tool | Free | +| Strategyzer | Full strategy toolkit (canvas + business model) | Paid | + +### Google Sheets Quick Setup + +1. Create a spreadsheet with factors as rows +2. Add columns for each competitor and your proposed offering +3. Rate each cell 1-5 +4. Select all data and insert a radar chart or line chart +5. Format: competitors in gray/muted colors, your proposed curve in bold color + +### Tips for Digital Canvases + +- Always include a legend explaining what the ratings mean +- Use color coding: red for factors to eliminate, orange for reduce, green for raise, blue for create +- Save versioned copies as the strategy evolves +- Include the date on every canvas (strategies age quickly) + +## Strategy Canvas Checklist + +Before finalizing your strategy canvas, verify: + +- [ ] Factors represent buyer-perceived value, not internal metrics +- [ ] 8-14 factors are included (not too few, not too many) +- [ ] Both functional and emotional factors are represented +- [ ] At least 3 competitors or strategic groups are plotted +- [ ] Ratings are validated by customer-facing team members +- [ ] Your proposed curve is divergent (not parallel) to competitors +- [ ] Your proposed curve is focused (high on 3-4 factors, not everything) +- [ ] You can describe your strategy in one compelling tagline +- [ ] The canvas has been reviewed by someone outside the team for blind spots +- [ ] The ERRC grid is consistent with the curve (eliminate = low, create = high) diff --git a/.agents/skills/blue-ocean-strategy/references/value-innovation.md b/.agents/skills/blue-ocean-strategy/references/value-innovation.md new file mode 100644 index 00000000..7de68cd0 --- /dev/null +++ b/.agents/skills/blue-ocean-strategy/references/value-innovation.md @@ -0,0 +1,277 @@ +# Value Innovation + +Value innovation is the cornerstone of blue ocean strategy. It occurs when a company aligns innovation with utility, price, and cost positions to deliver a leap in value for both buyers and the company simultaneously. This reference provides deep frameworks for understanding, identifying, and testing value innovation opportunities. + +## What Value Innovation Is + +Value innovation breaks the conventional assumption that companies must choose between differentiation and low cost. Instead of making a trade-off, value innovation pursues both simultaneously. + +**The core logic:** + +| Dimension | Traditional Strategy | Value Innovation | +|-----------|---------------------|------------------| +| Value | Deliver more value at higher cost | Deliver more value at lower cost | +| Innovation | Technology-driven, often ahead of buyer readiness | Buyer-value-driven, aligned with what customers actually need | +| Cost | Accept higher costs for differentiation | Reduce costs by eliminating and reducing | +| Competition | Benchmark against rivals | Make rivals irrelevant | +| Customers | Serve existing customers better | Convert non-customers into customers | + +Value innovation is NOT about being first to market. It is NOT about breakthrough technology. It is about making a leap in the value delivered to buyers while simultaneously driving down costs. + +## The Value Innovation Formula + +``` +Value Innovation = Buyer Utility x Accessible Price x Achievable Cost +``` + +All three must be aligned: + +### 1. Buyer Utility + +The offering must deliver a clear leap in utility that buyers immediately recognize. This is not incremental improvement. It is a qualitative shift in what the buyer experiences. + +**Test questions:** +- Would a first-time buyer understand the value in under 30 seconds? +- Is the utility leap obvious without explanation? +- Does it solve a problem buyers have accepted as "just the way things are"? + +### 2. Accessible Price + +The price must be set to attract the mass of target buyers. Price is not based on cost-plus. It is based on what alternatives buyers currently use. + +**Test questions:** +- Is the price within reach of the target mass market? +- Is it priced against alternatives (not just direct competitors)? +- Would the price point unlock demand from non-customers? + +### 3. Achievable Cost + +The cost structure must allow the company to earn a healthy profit at the strategic price point. Cost is achieved through elimination and reduction, not through subsidies or scale assumptions. + +**Test questions:** +- Can you achieve the target cost from day one (not "after scale")? +- Does the ERRC grid eliminate enough cost to fund what you create? +- Is the cost structure sustainable without external funding? + +## Value Innovation vs. Other Innovation Types + +Understanding what value innovation is NOT is as important as understanding what it is. + +### Value Innovation vs. Technology Innovation + +| Dimension | Technology Innovation | Value Innovation | +|-----------|-----------------------|------------------| +| **Starting point** | What is technically possible | What buyers need | +| **Risk** | Technology may not find a market | Lower risk because demand is validated | +| **Pricing** | Cost-plus (high R&D = high price) | Strategic pricing against alternatives | +| **Examples** | Segway, Google Glass, Concorde | Cirque du Soleil, Southwest Airlines, Wii | +| **Failure mode** | Brilliant technology nobody wants to buy | Rare, because it starts from buyer value | + +The Segway was a technology innovation marvel. It was not value innovation because it did not align utility, price, and cost for a mass market. The Nintendo Wii used less advanced technology than PS3 but delivered greater value innovation. + +### Value Innovation vs. Market Pioneering + +| Dimension | Market Pioneering | Value Innovation | +|-----------|-------------------|------------------| +| **Focus** | Being first | Being different in value delivery | +| **Timing** | First-mover advantage | Can be a fast follower | +| **Risk** | High (educating market) | Lower (addressing known pain) | +| **Examples** | Friendster (social networking), TiVo (DVR) | Facebook (social), Netflix (streaming) | +| **Outcome** | Often captured by followers | Sustainable if execution is strong | + +Being first matters far less than being the first to deliver value innovation. Facebook was not the first social network. Netflix was not the first streaming service. They were the first to deliver value innovation in their categories. + +### Value Innovation vs. Incremental Improvement + +| Dimension | Incremental Improvement | Value Innovation | +|-----------|------------------------|------------------| +| **Magnitude** | 10-20% better | 2x-10x different | +| **Factors** | Improve existing factors | Create new factors, eliminate old ones | +| **Competition** | Still competing on same terms | Changes the terms of competition | +| **Curve** | Same shape, slightly higher | Completely different shape | +| **Example** | iPhone 14 vs. iPhone 13 | Original iPhone vs. Blackberry | + +## How to Identify Value Innovation Opportunities + +### Step 1: Map the Current Value Curve + +List all factors your industry competes on. Rate each factor (low to high) for your company and the industry average. Look for convergence: if everyone's curves look similar, the industry is ripe for value innovation. + +### Step 2: Identify Over-Served Factors + +Ask: Which factors does the industry invest heavily in, but customers do not proportionally value? + +**Signals of over-serving:** +- Customers do not use advanced features +- Buyers choose the cheapest adequate option +- Industry differentiators do not correlate with purchase decisions +- Customer satisfaction surveys show diminishing returns on certain factors + +### Step 3: Identify Under-Served Pain Points + +Ask: Where do buyers experience friction, frustration, or workarounds that the industry ignores? + +**Discovery methods:** +- Observe customers using the product (not just ask them) +- Study complaint patterns and support tickets +- Interview non-customers about why they refuse the industry +- Map the entire buyer experience cycle for pain points + +### Step 4: Identify Cross-Industry Solutions + +Ask: How do alternative industries solve similar problems differently? + +**Process:** +- List all alternatives buyers consider (not just competitors) +- Study what those alternatives do better +- Identify transferable elements + +### Step 5: Apply the ERRC Grid + +Use the Four Actions Framework to design a new value curve that eliminates/reduces cost drivers and raises/creates new value elements. + +### Step 6: Validate Against the Three Criteria + +Confirm your proposed offering satisfies all three: + +| Criterion | Validation Method | +|-----------|-------------------| +| Buyer utility leap | Can buyers articulate the value unprompted after seeing it? | +| Accessible price | Is it priced within the corridor of alternatives? | +| Achievable cost | Does the ERRC math work at the strategic price? | + +## Testing Whether Your Strategy Is Value Innovation + +Use this diagnostic to evaluate any proposed strategy or existing business. + +### The Value Innovation Scorecard + +Rate each statement 1-5 (1 = strongly disagree, 5 = strongly agree): + +| # | Statement | Score | +|---|-----------|-------| +| 1 | Our offering eliminates factors the industry takes for granted | /5 | +| 2 | Our offering creates factors the industry has never offered | /5 | +| 3 | Our cost structure is lower than industry average | /5 | +| 4 | Our buyer utility is higher than industry average | /5 | +| 5 | We primarily attract non-customers, not competitors' customers | /5 | +| 6 | Our strategy canvas shows a divergent curve from competitors | /5 | +| 7 | Our price is set against alternatives, not cost-plus | /5 | +| 8 | Competitors cannot imitate us without dismantling their model | /5 | +| 9 | We can explain our value proposition in one simple sentence | /5 | +| 10 | Our offering is simpler than what the industry currently provides | /5 | + +**Scoring:** +- 40-50: Strong value innovation +- 30-39: Partial value innovation, strengthen weak areas +- 20-29: More incremental than innovative, revisit ERRC +- Below 20: Red ocean strategy, fundamental rethink needed + +## Common Misconceptions About Value Innovation + +### Misconception 1: "Value innovation means low price" + +Value innovation means the right price for the mass of target buyers, set against alternatives. Cirque du Soleil charges MORE than a traditional circus. The price is lower than Broadway theater, which is the relevant alternative for its target buyers. + +### Misconception 2: "We need new technology" + +Most value innovations use existing technology in new combinations. Southwest Airlines uses the same planes as everyone else. Yellow Tail uses standard winemaking. The innovation is in the value proposition, not the technology. + +### Misconception 3: "Value innovation means compromise" + +Value innovation is not about offering "less for less" or finding a mediocre middle ground. It is about being radically better on certain dimensions while deliberately choosing not to compete on others. This is not compromise. It is strategic focus. + +### Misconception 4: "Our industry is different" + +Value innovation has been demonstrated in every industry studied: airlines, wine, gaming, fitness, entertainment, technology, healthcare, education, financial services, and government. No industry is immune to blue ocean creation. + +### Misconception 5: "Customers told us what they want" + +Customers can articulate problems with current offerings but rarely envision value innovation. Henry Ford's apocryphal quote applies: customers would have asked for faster horses. Value innovation comes from observing behavior and pain points, not from asking customers to design the solution. + +### Misconception 6: "We need to serve everyone" + +Value innovation requires choosing. You will deliberately not serve some existing customers. Southwest does not serve business travelers wanting lie-flat seats. That is by design. The customers you give up are fewer than the non-customers you gain. + +## Team Exercises for Identifying Value Innovation + +### Exercise 1: The Industry Assumption Audit (45 minutes) + +**Objective:** Surface hidden assumptions that constrain strategic thinking. + +**Process:** +1. Each team member writes down 10 things "everyone in our industry knows to be true" +2. Combine and deduplicate the list +3. For each assumption, ask: "What if this were not true?" +4. Rate each assumption: How much cost does it drive? How much do buyers actually care? +5. Identify the assumptions with high cost and low buyer value + +**Output:** A ranked list of industry assumptions ripe for challenge. + +### Exercise 2: The Buyer Pain Diary (1 week) + +**Objective:** Identify utility gaps through direct observation. + +**Process:** +1. Assign team members to observe 3-5 customers using your product/service +2. Document every moment of friction, confusion, delay, or workaround +3. Note what customers do before and after using your product +4. Catalog emotional reactions (frustration, delight, indifference) +5. Synthesize patterns across observations + +**Output:** A pain point map organized by buyer experience stage. + +### Exercise 3: The Alternative Landscape (60 minutes) + +**Objective:** Discover value innovation opportunities by studying how alternatives solve buyer needs. + +**Process:** +1. Define the buyer's fundamental job-to-be-done +2. List every alternative way buyers accomplish this job (including non-consumption) +3. For each alternative, list its advantages over your industry +4. Identify which advantages could be incorporated into your offering +5. Map which of your industry's factors are irrelevant to buyers who choose alternatives + +**Output:** A cross-industry insight map showing transferable value elements. + +### Exercise 4: The Non-Customer Interview (2 weeks) + +**Objective:** Understand why people refuse your industry. + +**Process:** +1. Identify 5-10 non-customers from each of the three tiers +2. Conduct 30-minute interviews focused on: Why don't you use [industry]? What do you do instead? What would have to change for you to consider it? +3. Synthesize patterns across interviews +4. Identify the most commonly cited barriers +5. Design ERRC actions to address top barriers + +**Output:** A non-customer barrier analysis with ERRC response plan. + +### Exercise 5: The Value Innovation Canvas (90 minutes) + +**Objective:** Design a new value curve that breaks the value-cost trade-off. + +**Process:** +1. Draw the current industry strategy canvas (all competitors' curves) +2. Using insights from Exercises 1-4, propose factors to eliminate and reduce +3. Calculate the cost savings from elimination and reduction +4. Propose factors to raise and create using those freed resources +5. Draw the new value curve +6. Test: Is the new curve divergent? Is it focused? Does it have a compelling tagline? + +**Output:** A before/after strategy canvas with ERRC grid and cost/value analysis. + +## Value Innovation Decision Matrix + +When evaluating whether a proposed strategy qualifies as value innovation, use this decision matrix. + +| Question | Yes | No | +|----------|-----|-----| +| Does it eliminate factors competitors invest in? | Continue | Rethink: you are adding cost without reducing it elsewhere | +| Does it create factors the industry has never offered? | Continue | Rethink: you are optimizing within existing boundaries | +| Is the net cost lower than industry average? | Continue | Rethink: the elimination and reduction are not aggressive enough | +| Is the buyer utility a clear leap (not incremental)? | Continue | Rethink: the creation and raising are not bold enough | +| Can non-customers explain the value in their own words? | Continue | Rethink: the value is not intuitive enough | +| Is the strategy canvas curve divergent from competitors? | **Value Innovation** | Rethink: you may still be competing on the same factors | + +If any answer is "No," revisit the ERRC grid and push harder on elimination and creation until all answers are "Yes." diff --git a/.agents/skills/clean-architecture/SKILL.md b/.agents/skills/clean-architecture/SKILL.md new file mode 100644 index 00000000..a95fdf86 --- /dev/null +++ b/.agents/skills/clean-architecture/SKILL.md @@ -0,0 +1,196 @@ +--- +name: clean-architecture +description: 'Structure software around the Dependency Rule: source code dependencies point inward from frameworks to use cases to entities. Use when the user mentions "architecture layers", "dependency rule", "ports and adapters (hexagonal)", "onion architecture", "screaming architecture", "where should business logic go", "decouple from the database", "swap the framework without a rewrite", or "keep business rules independent". Also trigger when deciding which layer code belongs in, isolating core logic from infrastructure, defining module boundaries, or debating whether the framework should call your code or the reverse. Covers component principles, boundaries, and SOLID. For code-level quality, see clean-code. For domain modeling, see domain-driven-design.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Clean Architecture Framework + +A disciplined approach to structuring software so that business rules remain independent of frameworks, databases, and delivery mechanisms. Apply these principles when designing system architecture, reviewing module boundaries, or advising on dependency management. + +## Core Principle + +**Source code dependencies must point inward — toward higher-level policies.** Nothing in an inner circle can know anything about an outer circle. This single rule produces systems that are testable and independent of frameworks, UI, database, and any external agency. Business rules are what matter; databases, web frameworks, and delivery mechanisms are details — when details depend on policies, you can defer decisions, swap implementations, and test business logic in isolation. + +## Scoring + +**Goal: 10/10.** Score one point for each of the seven Quick Diagnostic rows the architecture satisfies (0-7), then map to a 0-10 band: 6-7 satisfied = **9-10** (Dependency Rule holds, business logic is framework- and DB-independent); 4-5 = **6-8** (core is testable but some details leak inward); 2-3 = **3-5** (framework or persistence dictates structure); 0-1 = **0-2** (no boundaries — business rules live in controllers and ORM models). Report the score, the failed diagnostic rows, and the specific inversion needed to fix each. + +### 1. Dependency Rule and Concentric Circles + +**Core concept:** Organize the architecture as concentric circles — Entities (enterprise business rules) innermost, then Use Cases (application business rules), then Interface Adapters, with Frameworks and Drivers outermost. Source code dependencies always point inward. + +**Why it works:** When high-level policies don't depend on low-level details, you can swap the database, web framework, or API style without touching business logic — the system becomes resilient to the most volatile parts of the stack. + +**Key insights:** +- Inner circles cannot mention outer circle names — no classes, functions, variables, or data formats from outside +- Data crossing a boundary must be in the form most convenient for the inner circle, never dictated by the outer +- Dependency Inversion (interfaces defined inward, implemented outward) is the mechanism that enforces the rule +- The number of circles is not fixed — four is typical; the rule stays the same +- Frameworks are details, not architecture — they belong in the outermost circle + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Layer direction** | Inner circles define interfaces; outer implement | `UserRepository` interface in Use Cases; `PostgresUserRepository` in Adapters | +| **Data crossing** | DTOs cross boundaries, not ORM entities | Use Case returns `UserResponse` DTO, not an ActiveRecord model | +| **Dependency direction** | Import arrows always point inward | Controller imports Use Case; Use Case never imports Controller | + +See [references/dependency-rule.md](references/dependency-rule.md) when an inner-circle import points outward and you need the four-circle code walkthrough, the data-crossing rules, and the four-step dependency-inversion procedure to fix it. + +### 2. Entities and Use Cases + +**Core concept:** Entities encapsulate enterprise-wide business rules — rules that would exist even without software. Use Cases contain application-specific rules that orchestrate the flow of data to and from Entities. + +**Why it works:** Separating what the business does (Entities) from how the application orchestrates it (Use Cases) lets you reuse Entities across applications and change application behavior without altering core business rules. + +**Key insights:** +- Entities are not database rows — they are objects or pure functions encapsulating critical business rules +- Use Cases accept Request Models and return Response Models — never framework objects +- Each Use Case is a single application operation (`CreateOrder`, `ApproveExpense`) +- The Interactor pattern: a Use Case class implements an input boundary interface and calls an output boundary interface +- Changes to a Use Case should never affect an Entity; Entity changes may ripple to Use Cases + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Entity design** | Critical business rules, zero framework dependencies | `Order.calculateTotal()` applies tax rules; knows nothing about HTTP | +| **Request/Response** | Simple data structures cross the boundary | `CreateOrderRequest { items, customerId }` — no ORM models | +| **Single responsibility** | One Use Case per operation | `PlaceOrder`, `CancelOrder`, `RefundOrder` as separate classes | +| **Interactor** | Implements Input Port, calls Output Port | `PlaceOrderInteractor implements PlaceOrderInput` | + +See [references/entities-use-cases.md](references/entities-use-cases.md) when designing an Interactor or deciding what belongs in an Entity versus a Use Case — full Enterprise vs. Application Business Rules treatment with request/response model examples. + +### 3. Interface Adapters and Frameworks + +**Core concept:** Interface Adapters convert data between the form convenient for Use Cases/Entities and the form required by external agencies. Frameworks and Drivers are the outermost layer — glue code to the outside world. + +**Why it works:** When the web framework, ORM, or message queue is confined to the outer circles, replacing any of them is a localized change. The database is a detail; the web is a detail; details should be plugins to your business rules, not the skeleton of the application. + +**Key insights:** +- Controllers translate HTTP into Use Case input; Presenters translate Use Case output into view models +- Gateways implement repository interfaces defined by Use Cases — the inner circle defines the contract, the outer fulfills it +- Business rules never know whether data lives in SQL, NoSQL, or flat files, or that delivery is HTTP +- Treat frameworks with suspicion — they want you to couple to them; keep them at arm's length + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Controller** | Delivery mechanism → Use Case input | `OrderController.create(req)` builds `CreateOrderRequest`, calls Interactor | +| **Presenter** | Use Case output → view model | `OrderPresenter.present(response)` formats for JSON/HTML | +| **Gateway** | Repository interface implemented per DB | `SqlOrderRepository implements OrderRepository` | +| **Framework boundary** | Framework calls inward, never the reverse | Express route handler calls Controller; Controller never imports Express | + +See [references/adapters-frameworks.md](references/adapters-frameworks.md) when wiring controllers, presenters, or gateways, or arguing that the database/web is a detail — covers plugin architecture and how to confine a framework to the edges. + +### 4. Component Principles + +**Core concept:** Components are the units of deployment. Three cohesion principles govern what goes inside a component; three coupling principles govern relationships between components. + +**Why it works:** Poorly composed components create ripple effects where one change forces redeployment of unrelated code; the principles keep changes localized and releases independent. + +**Key insights:** +- REP (Reuse/Release Equivalence): classes in a component must be versionable and releasable as a unit +- CCP (Common Closure): classes that change for the same reason at the same time belong together — SRP for components +- CRP (Common Reuse): don't force users to depend on classes they don't use +- ADP (Acyclic Dependencies): the component graph must have no cycles — break them with DIP or a new component +- SDP (Stable Dependencies): depend in the direction of stability +- SAP (Stable Abstractions): stable components should be abstract; unstable ones concrete + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Component grouping** | Group classes that change together (CCP) | All order-related Use Cases in one component | +| **Breaking cycles** | Apply DIP to invert a dependency edge | Extract an interface into a new component to break the cycle | +| **Stability metrics** | Instability I = Ce / (Ca + Ce) | Many incoming, no outgoing deps → I near 0 (stable) | + +See [references/component-principles.md](references/component-principles.md) when grouping classes into deployable components or breaking a dependency cycle — each of REP, CCP, CRP, ADP, SDP, SAP worked through with the instability metric. + +### 5. SOLID Principles + +**Core concept:** Five class-and-module-level principles — Single Responsibility, Open-Closed, Liskov Substitution, Interface Segregation, Dependency Inversion — the mid-level building blocks that make the Dependency Rule possible. + +**Why it works:** Each principle addresses a specific way dependencies go wrong, preventing the rigidity, fragility, and immobility that turn codebases into legacy nightmares. + +**Key insights:** +- SRP: a module has one reason to change — it serves one actor (not "does one thing") +- OCP: extend behavior by adding new code, not modifying existing code — strategy and plugin patterns +- LSP: subtypes must be usable through the base interface without the client knowing — violated by unexpected exceptions or ignored methods +- ISP: clients should not depend on methods they don't use — fat interfaces create needless coupling +- DIP: high-level modules and low-level modules both depend on abstractions defined by the high-level module + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **SRP violation** | Class serves multiple actors | `Employee` handles pay (CFO), reporting (COO), persistence (CTO) | +| **OCP via strategy** | New behavior through new classes | Add `ExpressShipping` implementing `ShippingStrategy`; `Order` untouched | +| **LSP violation** | Subtype changes expected behavior | `Square extends Rectangle` breaks the `setWidth()`/`setHeight()` contract | +| **ISP application** | Split fat interfaces into role interfaces | `Printer`, `Scanner`, `Fax` instead of one `MultiFunctionDevice` | +| **DIP wiring** | High-level defines interface; low-level implements | `OrderService` depends on `PaymentGateway`, not `StripeClient` | + +See [references/solid-principles.md](references/solid-principles.md) when applying SRP/OCP/LSP/ISP/DIP to a specific class or diagnosing a violation — each principle worked through with code examples and the smell it prevents. + +### 6. Boundaries and Boundary Anatomy + +**Core concept:** A boundary is a line between things that matter and things that are details, implemented through polymorphism: dependencies cross pointing inward while control flow may cross either way. + +**Why it works:** Every boundary buys the option to defer a decision or swap an implementation; strategic boundary placement determines whether a system is a joy or a pain to maintain over years. + +**Key insights:** +- Full boundaries use reciprocal interfaces on both sides; partial boundaries use a simpler strategy or facade +- Humble Object pattern: split boundary code into a hard-to-test part (close to the boundary) and an easy-to-test part (the logic) +- Services are not automatically architectural boundaries — a microservice with a fat shared data model is a monolith with network calls +- Tests are the most isolated component: they depend inward, nothing depends on them +- Premature boundaries are expensive, but so are missing ones — draw them at points of likely volatility + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Full vs. partial boundary** | Reciprocal ports, or a lone strategy | Use Case defines `PlaceOrderInput`/`PlaceOrderOutput`; simpler cases take a `ShippingStrategy` | +| **Humble Object** | Separate testable logic from infrastructure | `PresenterLogic` (testable) produces `ViewModel`; `View` (humble) renders it | +| **Main as plugin** | Composition root assembles the system | `main()` wires all concrete implementations and starts the app | + +See [references/boundaries.md](references/boundaries.md) when deciding where to draw a boundary, choosing full vs. partial, or applying the Humble Object pattern — also covers services as boundaries, test boundaries, and Main as the ultimate plugin. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| **ORM leaking into business logic** | Entities couple to the schema; DB changes rewrite business rules | Separate domain entities from persistence models; map at the adapter layer | +| **Business rules in controllers** | Untestable without HTTP; duplicated across endpoints | Move logic into Use Case Interactors; controllers only translate and delegate | +| **Framework-first architecture** | Framework dictates structure; swapping means a rewrite | Treat the framework as a plugin; structure code by business capability | +| **Circular component dependencies** | Changes ripple unpredictably; no independent releases | Apply DIP or extract a shared abstraction component | +| **One giant Use Case per feature** | Bloated thousand-line orchestrators | Split into focused single-operation Use Cases | +| **Skipping boundaries "because it's simple"** | Coupling accumulates silently until the cost is enormous | Draw boundaries proactively at points of likely volatility | +| **Microservices as automatic good architecture** | A distributed monolith is worse than a clean monolith | Apply the Dependency Rule within and across services; services are deployment boundaries, not architectural ones | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Can you test business rules without DB, web server, or framework? | Rules coupled to infrastructure | Extract entities and use cases behind interfaces; mock outer layers | +| Do all source dependencies point inward? | Dependency Rule violated | Introduce boundary interfaces; invert the offending dependency | +| Can you swap the database without touching business logic? | Persistence leaking inward | Repository pattern; isolate persistence in adapters | +| Are Use Cases independent of delivery mechanism? | Use Cases know HTTP/CLI/queues | Use plain DTOs in Use Case signatures | +| Is the framework confined to the outermost circle? | Framework is your architecture | Wrap framework calls behind interfaces; push to the edges | +| Is the component graph cycle-free? | Circular dependencies exist | Apply ADP: DIP or new components to break every cycle | +| Does Main (composition root) wire all dependencies? | Concrete classes instantiated in inner circles | Move construction to Main; use DI or factories | + +## Further Reading + +Based on Robert C. Martin's definitive guide to software architecture: + +- [*"Clean Architecture: A Craftsman's Guide to Software Structure and Design"*](https://www.amazon.com/Clean-Architecture-Craftsmans-Software-Structure/dp/0134494164?tag=wondelai00-20) by Robert C. Martin + +## About the Author + +**Robert C. Martin ("Uncle Bob")** is a software engineer programming since 1970, a founding signatory of the Agile Manifesto, and the author of *Clean Code*, *The Clean Coder*, *Clean Architecture*, and *Clean Agile*. His SOLID principles are foundational vocabulary in object-oriented design, and his work argues that architecture is about managing dependencies and keeping business rules independent of infrastructure details. diff --git a/.agents/skills/clean-architecture/references/adapters-frameworks.md b/.agents/skills/clean-architecture/references/adapters-frameworks.md new file mode 100644 index 00000000..a235a3fa --- /dev/null +++ b/.agents/skills/clean-architecture/references/adapters-frameworks.md @@ -0,0 +1,358 @@ +# Interface Adapters and Frameworks + +Interface Adapters and Frameworks & Drivers form the two outermost circles of Clean Architecture. Interface Adapters translate data between the forms convenient for Use Cases and Entities and the forms convenient for external agencies. Frameworks and Drivers are the glue code that connects the system to the outside world. Together, these layers contain all the volatile, technology-specific decisions -- the parts most likely to change over the life of a system. + +This reference covers controllers, presenters, gateways, the nature of frameworks as details, database and web as details, keeping frameworks at arm's length, and the plugin architecture. + + +## Table of Contents +1. [Interface Adapters](#interface-adapters) +2. [Frameworks as Details](#frameworks-as-details) +3. [The Database Is a Detail](#the-database-is-a-detail) +4. [The Web Is a Detail](#the-web-is-a-detail) +5. [Plugin Architecture](#plugin-architecture) +6. [Keeping Frameworks at Arm's Length](#keeping-frameworks-at-arms-length) + +--- + +## Interface Adapters + +### Controllers + +A Controller is an adapter that translates input from the delivery mechanism (HTTP, CLI, message queue, gRPC) into a form that the Use Case can understand. It constructs a Request Model and calls the Use Case's Input Port. + +**Responsibilities of a Controller:** +- Parse and extract data from the delivery mechanism's native format +- Construct the Use Case's Request Model +- Call the Use Case's Input Port +- Handle delivery-mechanism-specific concerns (authentication, rate limiting) BEFORE calling the Use Case + +**What a Controller must NOT do:** +- Contain business logic +- Directly access the database +- Format output for the response (that's the Presenter's job) +- Know about other controllers + +```python +# Controller in the Adapters circle +class OrderController: + def __init__(self, place_order: PlaceOrderInput): + self._place_order = place_order + + def create(self, http_request: dict) -> None: + # Translate HTTP data to Use Case request + request = PlaceOrderRequest( + customer_id=http_request["customer_id"], + items=[ + OrderItemRequest( + product_id=item["product_id"], + quantity=item["quantity"], + unit_price=item["unit_price"], + ) + for item in http_request["items"] + ], + shipping_address=AddressRequest( + street=http_request["address"]["street"], + city=http_request["address"]["city"], + zip_code=http_request["address"]["zip"], + ), + ) + # Delegate to the Use Case + self._place_order.execute(request) +``` + +The Controller knows about HTTP data format and knows about `PlaceOrderRequest`. It translates between the two. The Use Case never sees HTTP. + +### Presenters + +A Presenter translates Use Case output into a form suitable for the delivery mechanism. It implements the Use Case's Output Port and produces a View Model. + +**The Presenter pattern separates two concerns:** +1. The Use Case decides WHAT data to present +2. The Presenter decides HOW to format it for display + +```python +# Output Port defined in Use Case circle +class PlaceOrderOutput(ABC): + @abstractmethod + def present_success(self, response: OrderResponse) -> None: + pass + + @abstractmethod + def present_failure(self, message: str) -> None: + pass + +# Presenter in the Adapters circle +class JsonOrderPresenter(PlaceOrderOutput): + def __init__(self): + self.view_model: dict = {} + self.status_code: int = 200 + + def present_success(self, response: OrderResponse) -> None: + self.status_code = 201 + self.view_model = { + "data": { + "id": response.order_id, + "total": f"${response.total}", + "status": response.status.capitalize(), + "estimated_delivery": response.estimated_delivery, + } + } + + def present_failure(self, message: str) -> None: + self.status_code = 400 + self.view_model = {"error": {"message": message}} +``` + +The Presenter knows about JSON structure, status codes, and string formatting. The Use Case knows nothing about any of this. + +### Gateways + +A Gateway implements a repository or service interface defined by the Use Case circle using a specific technology. It is the adapter between the abstract port and the concrete implementation. + +```python +# Interface defined in Use Case circle +class OrderRepository(ABC): + @abstractmethod + def save(self, order: Order) -> None: + pass + + @abstractmethod + def find_by_id(self, order_id: str) -> Order | None: + pass + +# Gateway in the Adapters circle +class PostgresOrderRepository(OrderRepository): + def __init__(self, connection_pool): + self._pool = connection_pool + + def save(self, order: Order) -> None: + with self._pool.connection() as conn: + conn.execute( + "INSERT INTO orders (id, customer_id, total, status) VALUES (%s, %s, %s, %s)", + (order.id, order.customer_id, str(order.calculate_total()), order.status.value), + ) + for item in order.items: + conn.execute( + "INSERT INTO order_items (order_id, product_id, quantity, price) VALUES (%s, %s, %s, %s)", + (order.id, item.product_id, item.quantity, str(item.price)), + ) + + def find_by_id(self, order_id: str) -> Order | None: + with self._pool.connection() as conn: + row = conn.execute("SELECT * FROM orders WHERE id = %s", (order_id,)).fetchone() + if row is None: + return None + items = conn.execute("SELECT * FROM order_items WHERE order_id = %s", (order_id,)).fetchall() + return self._to_domain(row, items) + + def _to_domain(self, row, item_rows) -> Order: + # Map database rows back to domain entity + items = [OrderItem(r["product_id"], r["quantity"], Money(r["price"])) for r in item_rows] + return Order(order_id=row["id"], items=items, customer_id=row["customer_id"]) +``` + +Notice the `_to_domain` method: it maps between the persistence format (database rows) and the domain format (entity objects). This mapping is the gateway's core responsibility. + +### Adapter Types Summary + +| Adapter | Translates From | Translates To | Direction | +|---------|----------------|---------------|-----------| +| **Controller** | External input (HTTP, CLI, event) | Use Case Request Model | Inward | +| **Presenter** | Use Case Response Model | View Model (JSON, HTML, CLI output) | Outward | +| **Gateway** | Repository/Service Interface | Concrete technology (SQL, API, file) | Outward | +| **Mapper** | Domain Entity | Persistence Model (ORM, document) | Both directions | + +## Frameworks as Details + +### The Framework Trap + +Frameworks are powerful tools. They provide routing, dependency injection, ORM, template rendering, and dozens of other features. The temptation is to build your system on top of the framework -- to let the framework be the architecture. + +This is a trap. When the framework IS the architecture: +- You cannot test business logic without the framework running +- You cannot change the framework without rewriting the application +- Framework bugs become your bugs, in your most critical code +- Framework upgrades force changes throughout the system +- Your code becomes an accessory to the framework rather than the framework serving your code + +### Frameworks Want Marriage, You Want a Fling + +Frameworks are authored by people who have a use case for them. They provide massive power and convenience -- but they ask for commitment. They want you to: + +- Inherit from their base classes +- Put their annotations on your code +- Store your data in their preferred format +- Structure your project their way + +Each of these is a coupling point. The more you comply, the harder it is to separate. + +**The Clean Architecture approach:** +- Don't derive business objects from framework base classes +- Don't put framework annotations on domain entities +- Don't let the framework dictate your project structure +- Treat the framework as a tool in the outermost circle, not as the foundation + +### Practical Framework Isolation + +| Framework Feature | Coupled Approach | Decoupled Approach | +|-------------------|-----------------|-------------------| +| **Routing** | Business logic in route handlers | Route handlers call Controllers; Controllers call Use Cases | +| **ORM** | Domain entities ARE ORM models | Separate domain entities; map to/from ORM models in gateways | +| **Validation** | Framework validation decorators on entities | Validation in Use Case or domain layer using plain code | +| **Dependency injection** | `@Inject` annotations on domain classes | Constructor injection; wiring in Main component | +| **Configuration** | `Settings.get("key")` in business logic | Inject config values as constructor parameters | +| **Logging** | Framework logger called directly in Use Cases | Inject a logger interface; implement with framework in outer circle | + +## The Database Is a Detail + +The database is a detail. It is a mechanism for storing and retrieving data. From the perspective of the business rules, it doesn't matter whether data lives in PostgreSQL, MongoDB, flat files, or an in-memory data structure. + +### Why It Matters + +When business rules know about the database: +- Testing requires a database (slow, fragile tests) +- Database schema changes ripple into business logic +- Migrating to a different database means rewriting business rules +- The data model is driven by database capabilities rather than business needs + +### Repository Pattern + +The repository pattern is the primary mechanism for keeping the database at arm's length: + +1. **Define the interface in the Use Case circle** -- it describes WHAT operations the business needs, not HOW data is stored +2. **Implement the interface in the Adapter circle** -- this is where SQL, ORM calls, and database-specific code live +3. **Inject the implementation at startup** -- Main wires the concrete repository into the use case + +### ORM Considerations + +ORMs are useful tools, but they must be contained in the outer circles: + +**The two-model approach:** +- **Domain model**: Pure business entities with business methods and rules. No ORM annotations. Lives in the Entity circle. +- **Persistence model**: ORM-annotated classes that map to database tables. Lives in the Adapter circle. The gateway maps between the two. + +This duplication is intentional and valuable. The domain model evolves with business rules; the persistence model evolves with the database schema. They change for different reasons at different times. + +## The Web Is a Detail + +The web is a delivery mechanism -- a way to transport data between the user and the application. The business rules should not know whether they are being accessed through a web browser, a mobile app, a CLI, or a message queue. + +### Delivery Mechanism Independence + +When use cases are independent of the delivery mechanism, you can: +- Serve the same business logic through REST, GraphQL, gRPC, CLI, and WebSocket simultaneously +- Test business logic without HTTP +- Migrate from one web framework to another by rewriting only the outer circle + +### Multiple Delivery Mechanisms + +``` +REST Controller ----\ + \ +GraphQL Resolver ------> Use Case Interactor ---> Entity + / +CLI Command --------/ +Message Handler ---/ +``` + +Each delivery mechanism is an adapter in the outer circle. They all call the same Use Case Input Port. The business logic is written once and exposed through as many delivery mechanisms as needed. + +## Plugin Architecture + +The ultimate expression of Clean Architecture is the plugin architecture: the business rules are the core application, and everything else (database, web framework, external services, UI) is a plugin that connects to the core. + +### How Plugins Work + +1. **The core defines interfaces** (ports) that describe what it needs from the outside world +2. **Plugins implement those interfaces** using specific technologies +3. **Main assembles the plugins** and injects them into the core at startup +4. **The core never knows which plugins are attached** -- it only knows the interfaces + +### The Main Component + +Main is the dirtiest, most concrete component in the system. It knows about everything because it must instantiate and wire all the pieces together. But nothing depends on Main. + +```python +# main.py -- the composition root +def create_app(): + # Concrete infrastructure + db_pool = create_connection_pool(os.environ["DATABASE_URL"]) + email_client = SendGridClient(os.environ["SENDGRID_API_KEY"]) + + # Gateways (implement interfaces) + order_repo = PostgresOrderRepository(db_pool) + email_service = SendGridEmailService(email_client) + + # Presenters + order_presenter = JsonOrderPresenter() + + # Use Cases (wired with concrete dependencies) + place_order = PlaceOrderInteractor(order_repo, order_presenter) + cancel_order = CancelOrderInteractor(order_repo, email_service, order_presenter) + + # Controllers (wired with use cases) + order_controller = OrderController(place_order, cancel_order) + + # Framework wiring + app = Flask(__name__) + app.route("/orders", methods=["POST"])(order_controller.create) + app.route("/orders//cancel", methods=["POST"])(order_controller.cancel) + + return app +``` + +Main is the only place where the concrete classes from all circles come together. If you want to swap PostgreSQL for DynamoDB, you change Main and add a `DynamoOrderRepository`. No other file changes. + +### Plugin Swappability in Practice + +| Plugin | Interface | Implementation A | Implementation B | +|--------|-----------|-----------------|-----------------| +| **Persistence** | `OrderRepository` | `PostgresOrderRepository` | `DynamoOrderRepository` | +| **Email** | `EmailService` | `SendGridEmailService` | `SesEmailService` | +| **Payment** | `PaymentGateway` | `StripeGateway` | `BraintreeGateway` | +| **Search** | `ProductSearch` | `ElasticsearchProductSearch` | `AlgoliaProductSearch` | +| **Cache** | `CacheStore` | `RedisCacheStore` | `MemcachedCacheStore` | +| **File storage** | `FileStore` | `S3FileStore` | `LocalFileStore` | + +Each swap is a single line change in Main plus a new implementation class. No business logic changes. No use case changes. No entity changes. This is the power of treating frameworks and infrastructure as plugins. + +## Keeping Frameworks at Arm's Length + +### The Wrapper Strategy + +When a framework provides something useful but you don't want to couple to it directly, wrap it: + +```python +# Interface in inner circle +class Clock(ABC): + @abstractmethod + def now(self) -> datetime: + pass + +# Wrapper in outer circle +class SystemClock(Clock): + def now(self) -> datetime: + return datetime.utcnow() + +# Test double +class FakeClock(Clock): + def __init__(self, fixed_time: datetime): + self._time = fixed_time + + def now(self) -> datetime: + return self._time +``` + +Now your business logic depends on `Clock` (an interface you control), not on `datetime.utcnow()` (a library call you don't control). You can test time-dependent logic deterministically. + +### When NOT to Wrap + +Not everything needs a wrapper. Apply the rule pragmatically: + +- **Standard library types** (strings, lists, dates as data): Don't wrap. They are stable and ubiquitous. +- **Utility functions with no side effects**: Don't wrap `math.ceil()` or `json.dumps()`. +- **Anything with I/O or side effects** (database, network, filesystem, clock, random): Wrap it. +- **Anything from a framework you might swap**: Wrap it. + +The test is: "Would I need to mock this in a test?" If yes, wrap it behind an interface. diff --git a/.agents/skills/clean-architecture/references/boundaries.md b/.agents/skills/clean-architecture/references/boundaries.md new file mode 100644 index 00000000..a7e2a67c --- /dev/null +++ b/.agents/skills/clean-architecture/references/boundaries.md @@ -0,0 +1,431 @@ +# Boundaries and Boundary Anatomy + +Boundaries are the lines that separate software elements. In Clean Architecture, boundaries separate policies from details, stable code from volatile code, and high-level concerns from low-level mechanisms. How you draw boundaries, where you place them, and how you implement them determines whether a system remains maintainable over decades or degrades into an unmaintainable monolith. + +This reference covers boundary anatomy, boundary crossing mechanisms, the Humble Object pattern, partial boundaries, layers and boundaries, services as boundaries, test boundaries, and the Main component as the ultimate plugin. + + +## Table of Contents +1. [Boundary Anatomy](#boundary-anatomy) +2. [Boundary Crossing](#boundary-crossing) +3. [The Humble Object Pattern](#the-humble-object-pattern) +4. [Partial Boundaries](#partial-boundaries) +5. [Services as Boundaries](#services-as-boundaries) +6. [Test Boundaries](#test-boundaries) +7. [The Main Component as a Plugin](#the-main-component-as-a-plugin) + +--- + +## Boundary Anatomy + +### What Is a Boundary? + +A boundary is a separation between two groups of code where one side should not know about the other. At its core, a boundary is an interface plus a dependency inversion: the inner side defines an abstraction, and the outer side provides a concrete implementation. + +### The Structure of a Full Boundary + +A full boundary has components on both sides, connected through polymorphism: + +``` +[Client Side] [Boundary] [Implementation Side] + | +Controller ----calls----> InputPort (interface) + | + Interactor (implements InputPort) + | + Interactor ----calls----> OutputPort (interface) + | + Presenter (implements OutputPort) +``` + +**Both interfaces are defined on the inner side.** The Controller depends on `InputPort` (inward). The Presenter implements `OutputPort` (inward). The Interactor knows about neither the Controller nor the Presenter directly. + +### Boundary Components + +| Component | Circle | Role | +|-----------|--------|------| +| **Input Port** | Use Case | Interface that defines what the use case accepts | +| **Output Port** | Use Case | Interface that defines what the use case produces | +| **Interactor** | Use Case | Implements Input Port; calls Output Port | +| **Controller** | Adapter | Calls Input Port; translates from delivery mechanism | +| **Presenter** | Adapter | Implements Output Port; translates to display format | +| **Data Transfer Objects** | Use Case | Simple structures that carry data across the boundary | +| **Gateway Interface** | Use Case | Abstraction for data persistence or external services | +| **Gateway Implementation** | Adapter | Concrete persistence or service access | + +## Boundary Crossing + +### How Data Flows Across Boundaries + +Data crosses boundaries as simple data structures -- DTOs, structs, or primitives. Never as framework objects, ORM entities, or complex objects that carry dependencies. + +**Inbound crossing (Controller to Use Case):** + +```python +# Controller creates a simple DTO and passes it inward +@dataclass(frozen=True) +class TransferFundsRequest: + source_account_id: str + destination_account_id: str + amount: str # String to avoid float precision issues + currency: str + +# Controller +class TransferController: + def handle(self, http_body: dict) -> None: + request = TransferFundsRequest( + source_account_id=http_body["from"], + destination_account_id=http_body["to"], + amount=http_body["amount"], + currency=http_body["currency"], + ) + self._transfer_use_case.execute(request) +``` + +**Outbound crossing (Use Case to Presenter):** + +```python +# Use Case creates a response DTO and passes it outward through the Output Port +@dataclass(frozen=True) +class TransferFundsResponse: + transfer_id: str + new_source_balance: str + timestamp: str + +# In the Interactor: +response = TransferFundsResponse( + transfer_id=transfer.id, + new_source_balance=str(source_account.balance), + timestamp=transfer.created_at.isoformat(), +) +self._presenter.present_success(response) +``` + +### Flow of Control vs. Direction of Dependency + +This is a subtle but critical distinction: + +- **Flow of control:** Controller --> Interactor --> Presenter (left to right, outward at the end) +- **Source code dependency:** Controller --> InputPort <-- Interactor --> OutputPort <-- Presenter + +The dependencies point inward on both sides of the Interactor. Control flows outward to the Presenter, but the dependency is inverted: the Presenter depends on (implements) an interface defined by the Use Case. + +## The Humble Object Pattern + +### The Problem + +Some code is inherently hard to test because it's close to a boundary with something difficult to control -- a GUI, a database connection, a network socket. The Humble Object pattern splits such code into two parts: + +1. **The Humble Object:** Contains the hard-to-test code, stripped of all logic. It's so simple that testing is unnecessary (or trivially easy). +2. **The Testable Object:** Contains all the logic, extracted from the hard-to-test context so it can be tested in isolation. + +### Pattern Structure + +``` +[Testable Logic] [Humble Object] +PresenterLogic -produces-> ViewModel +(easy to test) (simple data) + | + v + View/Template + (hard to test, but so simple it doesn't matter) +``` + +### Examples of Humble Objects + +**1. View (GUI boundary):** + +```python +# Testable: Presenter that produces a ViewModel +class OrderPresenterLogic: + def present(self, response: OrderResponse) -> OrderViewModel: + return OrderViewModel( + title=f"Order #{response.order_id}", + total=f"${response.total:.2f}", + status_color="green" if response.status == "completed" else "yellow", + items=[f"{i.name} x{i.qty}" for i in response.items], + ) + +# Humble: View that just renders the ViewModel (no logic to test) +class OrderView: + def render(self, vm: OrderViewModel) -> str: + return self._template.render(vm) # Template rendering only +``` + +The Presenter is easily testable -- give it a response, assert the ViewModel. The View is humble -- it just passes the ViewModel to a template engine. No logic, no decisions. + +**2. Database Gateway (persistence boundary):** + +```python +# Testable: Use Case logic that decides what to persist +class ApproveExpenseInteractor: + def execute(self, request: ApproveExpenseRequest) -> None: + expense = self._repo.find_by_id(request.expense_id) + expense.approve(request.approver_id) # Business logic -- testable + self._repo.save(expense) + +# Humble: Repository that just maps and persists (minimal logic) +class SqlExpenseRepository: + def save(self, expense: Expense) -> None: + self._conn.execute( + "UPDATE expenses SET status = %s, approved_by = %s WHERE id = %s", + (expense.status.value, expense.approver_id, expense.id), + ) +``` + +The Interactor contains the decision logic (testable with a mock repo). The Repository is humble -- it just maps entity state to SQL parameters. + +**3. Service Gateway (external service boundary):** + +```python +# Testable: Logic that decides whether and how to send notifications +class NotificationService: + def __init__(self, sender: NotificationSender): + self._sender = sender + + def notify_order_shipped(self, order: Order) -> None: + if order.customer_prefers_email(): + self._sender.send_email( + to=order.customer_email, + subject=f"Order {order.id} shipped", + body=self._format_shipping_message(order), + ) + +# Humble: Just sends the message (hard to test, but no logic) +class SmtpNotificationSender(NotificationSender): + def send_email(self, to: str, subject: str, body: str) -> None: + self._smtp.sendmail(self._from_addr, to, self._build_mime(subject, body)) +``` + +### Where Humble Objects Appear in Clean Architecture + +| Boundary | Humble Object | Testable Partner | +|----------|--------------|-----------------| +| GUI/View | Template renderer, React component | Presenter logic that produces ViewModel | +| Database | SQL execution, ORM save/load | Use Case logic, mapping logic | +| External API | HTTP client wrapper | Service logic that decides what to send | +| Filesystem | File read/write operations | Logic that decides what to read/write | +| Clock/Random | System clock, random generator | Logic that uses injected clock/random | + +## Partial Boundaries + +### When Full Boundaries Are Too Expensive + +Full boundaries require interfaces on both sides (Input Port and Output Port), separate DTOs, and careful dependency management. Sometimes the anticipated need for a boundary doesn't justify the cost. In these cases, use a partial boundary. + +### Three Forms of Partial Boundaries + +**1. Skip the last step (prepare for full boundary later):** + +Create the interfaces and separate the components, but deploy them together in the same package. You've done the intellectual work of separation but deferred the deployment separation. + +```python +# Same package, but clearly separated with interfaces +# Can be split into separate packages later with minimal effort +class OrderService: + def __init__(self, repo: OrderRepository): # Interface exists + self._repo = repo + +class InMemoryOrderRepository(OrderRepository): # Implementation exists + ... + +# Both live in the same package for now +``` + +**2. Strategy pattern (one-sided boundary):** + +```python +# Only the outbound side has an interface +class ReportGenerator: + def __init__(self, formatter: ReportFormatter): + self._formatter = formatter + + def generate(self, data: ReportData) -> str: + # Logic here + return self._formatter.format(processed_data) + +class PdfFormatter(ReportFormatter): + def format(self, data) -> str: ... + +class CsvFormatter(ReportFormatter): + def format(self, data) -> str: ... +``` + +No Input Port, no Output Port -- just a simple strategy. Lighter weight than a full boundary. + +**3. Facade pattern (simplest):** + +```python +class OrderFacade: + """Single entry point to order subsystem. Hides internal complexity.""" + def place_order(self, items, customer_id): + # Delegates to internal classes + order = self._order_factory.create(items, customer_id) + self._order_repo.save(order) + self._notifier.notify(order) +``` + +The Facade provides a simpler interface but doesn't enforce dependency direction. It's the weakest form of boundary -- better than nothing, but easily violated. + +### Choosing Boundary Strength + +| Situation | Boundary Type | Cost | Protection | +|-----------|--------------|------|------------| +| Will definitely need to swap implementations | Full boundary (ports on both sides) | High | Complete | +| Might need to swap; want the option | Partial (interfaces, same package) | Medium | Good | +| Multiple strategies but stable architecture | Strategy pattern | Low-medium | Moderate | +| Just want to simplify access to a subsystem | Facade | Low | Minimal | +| Uncertain -- need might never arise | None (but document the decision) | Zero | None | + +## Services as Boundaries + +### Services Are Not Inherently Architectural + +A common misconception is that splitting a system into microservices automatically creates clean architectural boundaries. It does not. A microservice with a fat shared database or a shared data model is just a distributed monolith -- all the coupling of a monolith plus the complexity of network communication. + +### When Services Create Real Boundaries + +A service creates a genuine architectural boundary when: +- It has its own data store that no other service accesses directly +- It communicates through well-defined interfaces (API contracts) +- Its internal structure follows the Dependency Rule independently +- It can be developed, deployed, and scaled independently + +### When Services Fail as Boundaries + +| Anti-Pattern | Why It Fails | +|-------------|-------------| +| Shared database | Changes to the schema affect all services -- they're coupled | +| Shared data model library | All services import the same DTOs -- they change together | +| Synchronous orchestration | Service A calls B calls C calls D -- distributed monolith | +| Chatty communication | Services exchange many small calls -- performance and coupling | + +### Services Should Contain Clean Architecture + +Each service should have its own concentric circles internally: + +``` +Service Boundary +├── Entities (domain objects for this service's bounded context) +├── Use Cases (application logic for this service) +├── Adapters (controllers, gateways, presenters for this service) +└── Frameworks (HTTP server, database driver for this service) +``` + +The service boundary is a deployment boundary. The Clean Architecture circles within each service are architectural boundaries. Both are needed. + +## Test Boundaries + +### Tests as the Most Isolated Component + +Tests are the most decoupled component in any system. They depend on the code being tested, but nothing in the production system depends on the tests. Tests always point inward -- they test entities, use cases, and adapters, but no production code imports test code. + +### The Testing Boundary Structure + +``` +[Production Code] [Test Code] +Entity --------- B --> C --> A (CYCLE: A, B, C are effectively one component) + +A --> B --> C (NO CYCLE: DAG) + | ^ + v | + D --------/ +``` + +**Breaking cycles -- two strategies:** + +**Strategy 1: Apply the Dependency Inversion Principle** + +If B depends on A and A depends on B (cycle), extract an interface: + +``` +Before (cycle): + A <--> B + +After (no cycle): + A --> InterfaceX <-- B +``` + +A defines `InterfaceX`. B implements it. Now A depends on nothing new; B depends on `InterfaceX` (which lives with A). The cycle is broken. + +**Strategy 2: Extract a new component** + +Move the shared dependency into a new component that both A and B depend on: + +``` +Before (cycle): + A <--> B + +After (no cycle): + A --> C <-- B +``` + +C contains the shared classes. Both A and B depend on C. Neither depends on the other. + +### SDP: The Stable Dependencies Principle + +**"Depend in the direction of stability."** + +A component should only depend on components that are more stable than it is. Stability here means "difficulty of change" -- a component is stable if many other components depend on it (making it hard to change without breaking things). + +**Measuring stability:** + +- **Fan-in (Ca):** Number of classes outside the component that depend on classes inside the component (incoming dependencies) +- **Fan-out (Ce):** Number of classes inside the component that depend on classes outside the component (outgoing dependencies) +- **Instability (I):** I = Ce / (Ca + Ce), where I ranges from 0 (maximally stable) to 1 (maximally unstable) + +| Metric Value | Meaning | Implication | +|-------------|---------|-------------| +| I = 0 | Maximally stable (many dependents, no dependencies) | Hard to change; should be abstract | +| I = 1 | Maximally unstable (no dependents, many dependencies) | Easy to change; should be concrete | +| I = 0.5 | Balanced | Moderate change risk | + +**The SDP rule:** If Component A depends on Component B, then I(B) should be less than or equal to I(A). You should depend on things that are harder to change than you are. + +**Violation example:** +If a highly stable component (I=0.1, many dependents) depends on a highly unstable component (I=0.9, few dependents), the unstable component's frequent changes will destabilize all the stable component's dependents. + +### SAP: The Stable Abstractions Principle + +**"A component should be as abstract as it is stable."** + +Stable components (hard to change) should be abstract (contain mostly interfaces and abstract classes). This way, their stability does not prevent them from being extended. Unstable components (easy to change) should be concrete, containing the implementations that change frequently. + +**Measuring abstractness:** + +- **Nc:** Number of classes in the component +- **Na:** Number of abstract classes and interfaces in the component +- **Abstractness (A):** A = Na / Nc, where A ranges from 0 (fully concrete) to 1 (fully abstract) + +### The Main Sequence + +Plot each component on a graph with Instability (I) on the x-axis and Abstractness (A) on the y-axis. The ideal line runs from (0,1) to (1,0) -- the "Main Sequence." + +``` +A (Abstractness) +1 | * Zone of Uselessness + | \ + | \ <-- Main Sequence + | \ + | \ +0 |____________* Zone of Pain + 0 1 + I (Instability) +``` + +**Zone of Pain (I=0, A=0):** Maximally stable AND maximally concrete. Very hard to change but contains no abstractions for extension. Examples: database schemas, concrete utility libraries that everyone depends on. Painful to modify. + +**Zone of Uselessness (I=1, A=1):** Maximally unstable AND maximally abstract. No one depends on these abstract interfaces. They serve no purpose. Dead code. + +**The Main Sequence:** Components should fall near the line from (0,1) to (1,0). Stable components should be abstract. Unstable components should be concrete. + +**Distance from the Main Sequence:** +D = |A + I - 1|, where D ranges from 0 (on the line) to ~0.7 (in a zone). + +Components with high D values warrant investigation. + +## Practical Component Design + +### Component Mapping to Clean Architecture + +| Clean Architecture Circle | Stability | Abstractness | Character | +|--------------------------|-----------|-------------|-----------| +| **Entities** | Very stable (I near 0) | Abstract (interfaces, domain types) | Core business rules; many dependents | +| **Use Cases** | Stable (I = 0.2-0.4) | Moderately abstract (ports, interactors) | Application rules; depend on entities | +| **Adapters** | Unstable (I = 0.5-0.7) | Concrete (controllers, gateways) | Translation layer; depend on use cases | +| **Frameworks** | Very unstable (I near 1) | Concrete (configuration, wiring) | Glue code; depend on everything | + +### Versioning Components Independently + +When components are properly decoupled: +- Each can have its own version number +- Each can be released on its own schedule +- Teams can own components independently +- Breaking changes in one component can be managed through interface versioning + +### Component Design Workflow + +1. **Start with CCP:** Group classes by reason for change. Don't worry about component size. +2. **Apply CRP:** Remove classes that aren't used together. Split components that force unnecessary dependencies. +3. **Check REP:** Ensure each component has a coherent theme and can be meaningfully versioned. +4. **Graph dependencies:** Draw the component dependency graph. Look for cycles. +5. **Break cycles (ADP):** Use DIP or extraction to eliminate every cycle. +6. **Check stability direction (SDP):** Ensure dependencies flow toward stability. +7. **Balance abstraction (SAP):** Make stable components abstract; make unstable components concrete. +8. **Measure D:** Plot components on the I/A graph. Investigate those far from the Main Sequence. + +### Common Component Anti-Patterns + +| Anti-Pattern | Symptom | Fix | +|-------------|---------|-----| +| **God component** | One component contains everything | Split by CCP: group by reason for change | +| **Circular dependencies** | Can't release or build independently | Apply ADP: DIP or extraction | +| **Concrete stable component** | Many dependents, no abstractions, painful to change | Apply SAP: extract interfaces, move implementations to unstable components | +| **Unstable abstractions** | Abstract component with no dependents | Remove dead abstractions or rethink dependency structure | +| **Shotgun releases** | Changing one feature requires releasing five components | Apply CCP: group co-changing classes together | +| **Dependency magnet** | One utility component everyone depends on | Split into focused components; apply CRP | + +### Dependency Analysis Tools + +| Language | Tool | Purpose | +|----------|------|---------| +| Java | JDepend, ArchUnit | Measure component metrics, enforce dependency rules | +| JavaScript/TypeScript | Dependency Cruiser, Madge | Visualize and validate module dependencies | +| Python | import-linter, pydeps | Enforce import rules, visualize package dependencies | +| .NET | NDepend | Component metrics, dependency analysis | +| Go | `go vet`, custom linters | Package dependency validation | +| General | SonarQube | Cross-language dependency and quality analysis | + +These tools automate the detection of cycles, stability violations, and components in the Zone of Pain or Zone of Uselessness. Integrate them into CI/CD pipelines to prevent architectural drift. diff --git a/.agents/skills/clean-architecture/references/dependency-rule.md b/.agents/skills/clean-architecture/references/dependency-rule.md new file mode 100644 index 00000000..bb538de1 --- /dev/null +++ b/.agents/skills/clean-architecture/references/dependency-rule.md @@ -0,0 +1,245 @@ +# The Dependency Rule and Concentric Circles + +The Dependency Rule is the single most important concept in Clean Architecture. It states that source code dependencies can only point inward. Nothing in an inner circle can know anything at all about something in an outer circle. This includes names -- functions, classes, variables, data formats, or any other named software entity declared in an outer circle must not be mentioned by code in an inner circle. + +This reference covers the concentric circles model, how data crosses boundaries, why direction matters, how frameworks violate the rule, and how to keep the inner circle pure. + +## The Concentric Circles + +Clean Architecture organizes code into concentric circles, each representing a different level of abstraction and policy. The innermost circles contain the highest-level, most general policies. The outermost circles contain the lowest-level, most concrete details. + +### Circle 1: Entities (Innermost) + +Entities encapsulate enterprise-wide business rules. These are the most general, most stable rules in the system. They are the least likely to change when something external changes -- a page navigation change, a security policy change, or a database migration should not affect entities. + +**Characteristics of well-designed entities:** +- They can be simple objects with methods, or they can be a set of data structures and functions +- They encapsulate the most critical business rules +- They have no dependency on anything in the outer circles +- They would exist even if no software system existed (the rules are inherent to the business) +- They are the most reusable elements across different applications in the enterprise + +**Example:** + +```python +class LoanApplication: + def __init__(self, applicant_income: float, requested_amount: float, credit_score: int): + self.applicant_income = applicant_income + self.requested_amount = requested_amount + self.credit_score = credit_score + + def debt_to_income_ratio(self) -> float: + return self.requested_amount / (self.applicant_income * 12) + + def is_creditworthy(self) -> bool: + return self.credit_score >= 680 and self.debt_to_income_ratio() < 0.43 +``` + +This entity knows nothing about databases, HTTP, or frameworks. It encapsulates the business rule that determines creditworthiness. + +### Circle 2: Use Cases + +Use Cases contain application-specific business rules. They orchestrate the flow of data to and from entities and direct those entities to use their enterprise-wide business rules to achieve the goals of the use case. + +**Characteristics:** +- They define and implement input and output port interfaces +- They manipulate entities to achieve application goals +- Changes to use cases do not affect entities +- Changes to external layers (database, UI) do not affect use cases + +### Circle 3: Interface Adapters + +This circle contains adapters that convert data between the format most convenient for the use cases and entities and the format most convenient for some external agency such as the database or the web. + +**Contains:** +- Controllers (translate inbound requests to use case input) +- Presenters (translate use case output to external format) +- Gateways (implement repository interfaces using specific technologies) + +### Circle 4: Frameworks and Drivers (Outermost) + +The outermost layer is composed of frameworks and tools -- the database, the web framework, the messaging system. This is where all the details go. The web is a detail. The database is a detail. We keep these things on the outside where they can do little harm. + +**Contains:** +- Web framework (Express, Spring, Django, Rails) +- Database engine and ORM +- External service clients +- Device drivers and I/O + +## The Direction of Dependencies + +The arrow of dependency is not the same as the arrow of control flow. Control flow can go in any direction across a boundary. Source code dependencies, however, must always point inward. + +### How Control Flow Opposes Dependency Direction + +Consider this scenario: a controller needs to call a use case, and the use case needs to call a presenter. The control flows outward (from use case to presenter), but the dependency must point inward (presenter depends on use case, not the other way around). + +The mechanism is Dependency Inversion: + +``` +Controller --> [Use Case Input Port] <-- Use Case Interactor --> [Use Case Output Port] <-- Presenter +``` + +The Use Case defines both the Input Port (which the Controller calls) and the Output Port (which the Presenter implements). The Use Case never knows about the Controller or the Presenter directly. It only knows about the interfaces it defines. + +```python +# Defined in the Use Case circle +class PlaceOrderOutputPort(ABC): + @abstractmethod + def present_success(self, response: OrderResponse) -> None: + pass + + @abstractmethod + def present_failure(self, error: str) -> None: + pass + +# Defined in the Use Case circle +class PlaceOrderInteractor: + def __init__(self, order_repo: OrderRepository, presenter: PlaceOrderOutputPort): + self.order_repo = order_repo + self.presenter = presenter + + def execute(self, request: PlaceOrderRequest) -> None: + order = Order.create(request.items, request.customer_id) + self.order_repo.save(order) + self.presenter.present_success(OrderResponse(order.id, order.total)) + +# Defined in the Adapters circle -- implements the Use Case's interface +class JsonOrderPresenter(PlaceOrderOutputPort): + def present_success(self, response: OrderResponse) -> None: + self.view_model = {"order_id": response.id, "total": str(response.total)} + + def present_failure(self, error: str) -> None: + self.view_model = {"error": error} +``` + +The Interactor defines `PlaceOrderOutputPort`. The `JsonOrderPresenter` in the outer circle implements it. The dependency points inward even though control flows outward. + +## Data Crossing Boundaries + +When data crosses a boundary, it is always in the form that is most convenient for the inner circle. The outer circle must adapt its data into the form expected by the inner circle. + +### Principle: Inner Circle Dictates Data Format + +**Wrong -- outer circle format leaking inward:** + +```python +# Use Case receives a Django request object (framework dependency) +class CreateUserInteractor: + def execute(self, request: HttpRequest): # VIOLATION: knows about Django + data = json.loads(request.body) + user = User(name=data['name']) +``` + +**Right -- inner circle defines its own data structure:** + +```python +# Use Case defines its own request model +@dataclass +class CreateUserRequest: + name: str + email: str + +class CreateUserInteractor: + def execute(self, request: CreateUserRequest): # Pure data structure + user = User(name=request.name, email=request.email) +``` + +The Controller in the outer circle is responsible for translating the HTTP request into the `CreateUserRequest`. + +### Crossing Data Patterns + +| Pattern | When to Use | Example | +|---------|-------------|---------| +| **Request/Response DTOs** | Standard use case boundaries | `CreateOrderRequest` and `CreateOrderResponse` as plain data classes | +| **Primitives** | Simple boundaries with few parameters | `get_user(user_id: str) -> UserResponse` | +| **Domain events** | Communicating between bounded contexts | `OrderPlaced(order_id, timestamp)` emitted by inner circle | +| **Data maps (dicts)** | Crossing boundaries where type safety is less critical | Acceptable in dynamic languages; prefer typed DTOs in static ones | + +### What Must Not Cross Boundaries + +- **ORM entities or database rows**: These are outer circle artifacts. Never pass an ActiveRecord model into a Use Case. +- **Framework request/response objects**: `HttpRequest`, `HttpResponse`, `Request`, `Response` -- all belong in the outer circle. +- **Third-party library types**: If your Use Case accepts an `AwsS3Object`, you've coupled business logic to AWS. + +## How Frameworks Violate the Dependency Rule + +Frameworks want to be the center of your universe. They ask you to subclass their base classes, decorate your code with their annotations, and structure your project according to their conventions. Every such demand is a dependency pointing outward-to-inward -- a violation. + +### Common Framework Violations + +| Framework Pattern | Violation | Fix | +|-------------------|-----------|-----| +| **ORM annotations on entities** | Entity depends on database framework | Separate domain entity from ORM model; map between them | +| **Controller base classes** | Business logic inherits framework code | Use composition: controller holds a reference to the interactor | +| **Framework-specific return types** | Use Case returns `ResponseEntity` or `JsonResponse` | Return plain DTOs; let the adapter format the response | +| **Dependency injection via framework** | Inner circle annotated with `@Inject`, `@Autowired` | Use constructor injection with plain interfaces; wire in Main | +| **Validation annotations** | Business validation tied to framework | Validate in the use case using plain code or a domain validator | + +### Keeping Frameworks at Arm's Length + +The key insight is to treat the framework as a plugin, not as your architecture: + +1. **Don't derive from framework base classes** in your business logic. If the framework requires inheritance, create a thin adapter that inherits from the framework class and delegates to your clean inner code. + +2. **Don't scatter framework annotations** throughout your domain. If you must use annotations for ORM mapping, do so on a separate persistence model that maps to and from your domain entity. + +3. **Structure your project by business capability**, not by framework convention. Instead of `controllers/`, `models/`, `services/` (framework-driven), use `orders/`, `payments/`, `shipping/` (domain-driven), each with its own layers inside. + +## Keeping the Inner Circle Pure + +The inner circle is the most valuable part of the system because it contains the rules that make the business money. Protecting it from contamination requires vigilance. + +### Purity Checklist + +- **No imports from outer circles**: Grep your entity and use case code for imports of framework, database, or infrastructure packages. There should be none. +- **No I/O**: Inner circle code never reads from a file, queries a database, or makes an HTTP call directly. It calls an interface, and the outer circle provides the implementation. +- **No global state or singletons** that come from outer circles: If a use case accesses `Settings.DATABASE_URL`, it depends on infrastructure. +- **No concurrency primitives** from the framework: Threads, async runtime, and event loops are outer circle concerns. Use cases should be synchronous-looking; the adapter handles async mechanics. +- **Testable in isolation**: If you cannot instantiate a use case with mock implementations and run it without starting any server, database, or framework, the inner circle is not pure. + +### Enforcement Strategies + +| Strategy | How It Works | Tools | +|----------|-------------|-------| +| **Architecture tests** | Automated tests that verify import rules | ArchUnit (Java), Dependency Cruiser (JS/TS), import-linter (Python) | +| **Module boundaries** | Language-level visibility (packages, modules) | Java modules, Go internal packages, Rust `pub(crate)` | +| **Build system separation** | Inner and outer circles are separate build targets | Separate Gradle modules, npm packages, or Python packages | +| **Code review rules** | Manual review for dependency direction violations | PR checklist: "Do any new imports in the domain cross outward?" | + +### The Four-Step Inversion Process + +When you discover an outward dependency in an inner circle: + +1. **Identify the dependency**: What concrete outer-circle class is being referenced? +2. **Define an interface in the inner circle** that describes what the inner circle needs (not what the outer circle provides). +3. **Move the concrete implementation to the outer circle**, implementing the inner circle's interface. +4. **Wire the dependency in Main** (the composition root), injecting the concrete implementation into the inner circle at startup. + +This process always works. It may feel like ceremony, but it's the mechanism that keeps the most valuable code in your system independent of the most volatile. + +## The Dependency Rule in Practice: A Complete Example + +Consider an e-commerce system handling order placement: + +``` +[HTTP Layer] [Use Case Layer] [Entity Layer] +Express Route Handler --> PlaceOrderInteractor --> Order.create() + | Order.calculateTotal() + v + OrderRepository (interface) + ^ + | +[Persistence Layer] +PostgresOrderRepository (implements OrderRepository) +``` + +Dependencies: +- Express Route Handler depends on PlaceOrderInteractor (inward) -- correct +- PlaceOrderInteractor depends on Order (inward) -- correct +- PlaceOrderInteractor depends on OrderRepository interface (same circle) -- correct +- PostgresOrderRepository depends on OrderRepository interface (inward) -- correct +- Express Route Handler does NOT appear in any inner circle -- correct +- PostgreSQL does NOT appear in any inner circle -- correct + +The Dependency Rule is satisfied. The business rules (Order, PlaceOrderInteractor) know nothing about Express or PostgreSQL. You could swap both without changing a single line of business logic. diff --git a/.agents/skills/clean-architecture/references/entities-use-cases.md b/.agents/skills/clean-architecture/references/entities-use-cases.md new file mode 100644 index 00000000..02412c2b --- /dev/null +++ b/.agents/skills/clean-architecture/references/entities-use-cases.md @@ -0,0 +1,347 @@ +# Entities and Use Cases + +Entities and Use Cases form the two innermost circles of Clean Architecture. Entities contain Enterprise Business Rules -- the most general and highest-level rules. Use Cases contain Application Business Rules -- the automation rules specific to a particular application. Together, they represent the core value of the system, the code that is most worth protecting from external change. + +This reference covers entity design, use case structure, the interactor pattern, input/output boundaries, request/response models, and strategies for keeping use cases focused. + + +## Table of Contents +1. [Enterprise Business Rules (Entities)](#enterprise-business-rules-entities) +2. [Application Business Rules (Use Cases)](#application-business-rules-use-cases) +3. [Request and Response Models](#request-and-response-models) +4. [Keeping Use Cases Focused](#keeping-use-cases-focused) + +--- + +## Enterprise Business Rules (Entities) + +### What Is an Entity? + +An entity is an object within the system that embodies a small set of critical business rules operating on critical business data. The entity object either contains the critical business data or has easy access to it. The interface of the entity consists of the functions that implement the critical business rules. + +**Critical distinction:** An entity is not a database row. It is not an ORM model. It is not a struct that merely holds data. An entity encapsulates business rules -- logic that would exist even if there were no computer system at all. + +### Characteristics of Well-Designed Entities + +**1. Framework-independent:** +Entities do not inherit from database base classes, do not carry ORM annotations, and do not import framework packages. + +```python +# WRONG: Entity coupled to ORM +class Order(db.Model): # Inherits from SQLAlchemy + __tablename__ = 'orders' + id = db.Column(db.Integer, primary_key=True) + total = db.Column(db.Float) + +# RIGHT: Pure domain entity +class Order: + def __init__(self, order_id: str, items: list[OrderItem], customer_id: str): + self._id = order_id + self._items = items + self._customer_id = customer_id + self._status = OrderStatus.PENDING + + def calculate_total(self) -> Money: + subtotal = sum(item.price * item.quantity for item in self._items) + return subtotal + self._calculate_tax(subtotal) + + def _calculate_tax(self, subtotal: Money) -> Money: + # Business rule: tax calculation + return subtotal * Decimal("0.08") +``` + +**2. Business-rule containers:** +The methods on an entity enforce business invariants. They are not getters and setters -- they represent meaningful business operations. + +```python +class BankAccount: + def withdraw(self, amount: Money) -> None: + if amount > self._balance: + raise InsufficientFundsError(self._balance, amount) + if self._is_frozen: + raise AccountFrozenError(self._account_id) + self._balance -= amount + self._record_transaction(TransactionType.WITHDRAWAL, amount) +``` + +The `withdraw` method encapsulates business rules: you cannot withdraw more than the balance, and you cannot withdraw from a frozen account. These rules exist regardless of whether the system is a web app, a mobile app, or a batch process. + +**3. Stable over time:** +Entities change only when business rules change. A decision to migrate from PostgreSQL to DynamoDB should not require any entity modifications. A decision to change the web framework should not affect entities. + +**4. Testable in complete isolation:** +You should be able to instantiate an entity and call its methods in a unit test with zero setup -- no database, no framework, no configuration files. + +```python +def test_order_calculates_total_with_tax(): + items = [OrderItem("widget", Money("10.00"), quantity=3)] + order = Order("order-1", items, "customer-1") + assert order.calculate_total() == Money("32.40") # 30.00 + 2.40 tax +``` + +### Entity Design Patterns + +| Pattern | When to Use | Example | +|---------|-------------|---------| +| **Rich domain model** | Complex business rules with many invariants | `Order` with status transitions, validation, calculations | +| **Value objects** | Immutable concepts defined by their attributes | `Money(amount, currency)`, `Address(street, city, zip)` | +| **Aggregates** | Cluster of entities treated as a unit for data changes | `Order` aggregate contains `OrderItems`; external code accesses items only through `Order` | +| **Domain events** | Communicate that something meaningful happened | `Order.place()` produces `OrderPlaced` event | +| **Factory methods** | Complex construction that enforces invariants | `Order.create(items, customer)` validates and initializes | + +### Common Entity Mistakes + +| Mistake | Why It's Wrong | Fix | +|---------|---------------|-----| +| Anemic entities (data-only, no behavior) | Business rules scatter into services; entity is just a DTO | Move business logic into entity methods | +| ORM annotations on domain entities | Entity depends on database framework | Separate domain entity from persistence model | +| Entity knows about its repository | Entity depends on infrastructure | Pass dependencies into use cases, not entities | +| Public setters on everything | No invariant protection; any code can put entity in invalid state | Use methods that enforce business rules; make fields private | + +## Application Business Rules (Use Cases) + +### What Is a Use Case? + +A Use Case describes a single, specific application operation. It orchestrates entities and defines the application-specific rules for how data flows to and from those entities. It accepts input through a defined port, manipulates entities, and produces output through another defined port. + +**Critical distinction:** Use Cases are not entities. An entity encapsulates a business rule that would exist without software. A Use Case automates a specific application workflow that only makes sense within the context of the software system. + +### The Interactor Pattern + +The Interactor is the concrete class that implements a Use Case. The pattern has three parts: + +1. **Input Port (Input Boundary):** An interface that defines what the Use Case accepts. The Controller calls this interface. +2. **Interactor:** The concrete class that implements the Input Port and contains the application logic. +3. **Output Port (Output Boundary):** An interface that defines what the Use Case produces. The Presenter implements this interface. + +```python +# Input Port -- defined in the Use Case circle +class PlaceOrderInput(ABC): + @abstractmethod + def execute(self, request: PlaceOrderRequest) -> None: + pass + +# Output Port -- defined in the Use Case circle +class PlaceOrderOutput(ABC): + @abstractmethod + def present_success(self, response: OrderResponse) -> None: + pass + + @abstractmethod + def present_validation_error(self, errors: list[str]) -> None: + pass + + @abstractmethod + def present_failure(self, message: str) -> None: + pass + +# Interactor -- implements Input Port, uses Output Port +class PlaceOrderInteractor(PlaceOrderInput): + def __init__(self, order_repo: OrderRepository, presenter: PlaceOrderOutput): + self._order_repo = order_repo + self._presenter = presenter + + def execute(self, request: PlaceOrderRequest) -> None: + errors = self._validate(request) + if errors: + self._presenter.present_validation_error(errors) + return + + order = Order.create( + items=[OrderItem(i.product_id, i.quantity, i.price) for i in request.items], + customer_id=request.customer_id, + ) + + self._order_repo.save(order) + + response = OrderResponse( + order_id=order.id, + total=order.calculate_total(), + status=order.status.value, + ) + self._presenter.present_success(response) +``` + +### Input/Output Boundaries + +The boundaries are the interfaces that separate the Use Case circle from the circles on either side. They are defined in the Use Case circle and implemented by the outer circles. + +**Why boundaries matter:** +- The Controller depends on the Input Port (inward dependency -- correct) +- The Presenter depends on the Output Port (inward dependency -- correct) +- The Interactor depends on neither the Controller nor the Presenter (isolation preserved) + +### Alternative: Return-Based Use Cases + +Not every use case needs the full Output Port pattern. A simpler approach returns a result directly: + +```python +class PlaceOrderInteractor: + def __init__(self, order_repo: OrderRepository): + self._order_repo = order_repo + + def execute(self, request: PlaceOrderRequest) -> Result[OrderResponse, OrderError]: + errors = self._validate(request) + if errors: + return Failure(ValidationError(errors)) + + order = Order.create(...) + self._order_repo.save(order) + return Success(OrderResponse(order.id, order.calculate_total())) +``` + +This is simpler and often sufficient. Use the full Output Port pattern when the presentation logic is complex or when you need to support multiple presentation formats from the same use case. + +## Request and Response Models + +### Request Models + +Request models are simple data structures that carry input data across the boundary. They are defined in the Use Case circle. + +**Rules for request models:** +- No framework types (no `HttpRequest`, no `Form`, no `JsonNode`) +- No entity types (the controller maps external data to the request model; the interactor maps the request model to entity calls) +- Contain only primitives, strings, and simple nested structures +- May contain validation hints but not validation logic dependent on external state + +```python +@dataclass(frozen=True) +class PlaceOrderRequest: + customer_id: str + items: list[OrderItemRequest] + shipping_address: AddressRequest + coupon_code: str | None = None + +@dataclass(frozen=True) +class OrderItemRequest: + product_id: str + quantity: int + unit_price: str # String to avoid floating-point; Use Case converts to Money +``` + +### Response Models + +Response models carry output data across the boundary. They are defined in the Use Case circle. + +**Rules for response models:** +- No entity types -- the Use Case extracts the relevant data from entities and populates the response +- No framework types -- the Presenter (outer circle) converts the response into whatever format the delivery mechanism needs +- Contain only the data the outer circle needs to fulfill its role + +```python +@dataclass(frozen=True) +class OrderResponse: + order_id: str + total: str # Formatted money value + status: str + estimated_delivery: str | None + items: list[OrderItemResponse] + +@dataclass(frozen=True) +class OrderItemResponse: + product_name: str + quantity: int + line_total: str +``` + +### The Mapping Chain + +Data transforms at each boundary: + +``` +HTTP Request (JSON) + --> Controller maps to --> PlaceOrderRequest (DTO) + --> Interactor maps to --> Entity method calls + --> Entity produces result + --> Interactor maps to --> OrderResponse (DTO) + --> Presenter maps to --> ViewModel or JSON +--> HTTP Response +``` + +Each transformation is a boundary crossing. Each boundary is an opportunity to decouple. + +## Keeping Use Cases Focused + +### One Use Case, One Operation + +Each Use Case should represent a single application operation. If you find a Use Case doing multiple things, split it. + +**Signs of an unfocused Use Case:** +- The class name contains "And" (e.g., `CreateAndNotifyOrder`) +- The execute method has conditional branches for fundamentally different operations +- The class has more than 3-4 dependencies +- The test file has tests for unrelated scenarios + +### Use Case Granularity Guidelines + +| Granularity | Use Case Example | Notes | +|-------------|-----------------|-------| +| **Too coarse** | `ManageOrders` | Does everything -- create, update, cancel, refund | +| **Right level** | `PlaceOrder`, `CancelOrder`, `RefundOrder` | Each is a single operation with clear input and output | +| **Too fine** | `ValidateOrderItems`, `CalculateOrderTotal` | These are steps within a use case, not standalone operations | + +### Composing Use Cases + +Sometimes one application operation involves multiple steps that could be their own use cases. Two approaches: + +**1. Use Case calls Use Case (simple composition):** + +```python +class PlaceOrderAndSendConfirmation: + def __init__(self, place_order: PlaceOrderInput, send_confirmation: SendConfirmationInput): + self._place_order = place_order + self._send_confirmation = send_confirmation + + def execute(self, request: PlaceOrderRequest) -> None: + order_result = self._place_order.execute(request) + if order_result.is_success: + self._send_confirmation.execute( + SendConfirmationRequest(order_result.order_id) + ) +``` + +**2. Domain events (loose coupling):** + +The Use Case emits a domain event; another Use Case subscribes to it. This is better when the steps are truly independent and could happen asynchronously. + +### Use Case Dependencies + +A Use Case should depend on: +- **Entity types** (to call business rules) +- **Repository interfaces** (to load and persist entities) +- **Output port interfaces** (to present results) +- **Domain service interfaces** (for cross-entity business operations) + +A Use Case should NOT depend on: +- **Framework types** (HTTP, ORM, message queue) +- **Concrete infrastructure classes** (database client, email service) +- **Other use case concrete classes** (use input port interfaces instead) +- **Configuration or environment variables** (inject configuration as constructor parameters) + +### Testing Use Cases + +Use Cases should be the most thoroughly tested part of the system because they contain the application's automation rules. + +```python +def test_place_order_calculates_total_and_saves(): + # Arrange + mock_repo = MockOrderRepository() + mock_presenter = MockPlaceOrderPresenter() + interactor = PlaceOrderInteractor(mock_repo, mock_presenter) + + request = PlaceOrderRequest( + customer_id="cust-1", + items=[OrderItemRequest("prod-1", quantity=2, unit_price="25.00")], + shipping_address=AddressRequest("123 Main", "Springfield", "62704"), + ) + + # Act + interactor.execute(request) + + # Assert + assert mock_repo.saved_order is not None + assert mock_repo.saved_order.calculate_total() == Money("54.00") # 50 + 4 tax + assert mock_presenter.success_response.order_id == mock_repo.saved_order.id +``` + +No database. No web server. No framework. Just the use case logic running in a plain unit test. This is the payoff of the Dependency Rule. diff --git a/.agents/skills/clean-architecture/references/solid-principles.md b/.agents/skills/clean-architecture/references/solid-principles.md new file mode 100644 index 00000000..aef5c73d --- /dev/null +++ b/.agents/skills/clean-architecture/references/solid-principles.md @@ -0,0 +1,412 @@ +# SOLID Principles + +The SOLID principles are five design principles for managing dependencies at the class and module level. They were assembled and named by Robert C. Martin in the early 2000s, drawing on decades of software engineering wisdom. In Clean Architecture, SOLID principles serve as the mid-level building blocks that make the Dependency Rule possible. Without SOLID, the concentric circles would leak and the boundaries would crumble. + +This reference covers each principle with definitions, code examples, common violations, and practical application guidance. + + +## Table of Contents +1. [SRP: The Single Responsibility Principle](#srp-the-single-responsibility-principle) +2. [OCP: The Open-Closed Principle](#ocp-the-open-closed-principle) +3. [LSP: The Liskov Substitution Principle](#lsp-the-liskov-substitution-principle) +4. [ISP: The Interface Segregation Principle](#isp-the-interface-segregation-principle) +5. [DIP: The Dependency Inversion Principle](#dip-the-dependency-inversion-principle) + +--- + +## SRP: The Single Responsibility Principle + +**"A module should have one, and only one, reason to change."** + +More precisely: a module should be responsible to one, and only one, actor (a group of users or stakeholders who want the system to change in the same way). + +### Understanding SRP + +SRP is commonly misunderstood as "a function should do one thing." That's a good principle for functions, but SRP operates at a higher level. SRP says that the module (class) should serve one actor -- one group of people who would request changes. + +### Classic Violation + +```python +class Employee: + def calculate_pay(self) -> Money: + # Serves the CFO / accounting department + regular_hours = self._get_regular_hours() + overtime = self._get_overtime_hours() + return regular_hours * self.hourly_rate + overtime * self.hourly_rate * 1.5 + + def report_hours(self) -> HoursReport: + # Serves the COO / operations department + return HoursReport( + regular=self._get_regular_hours(), + overtime=self._get_overtime_hours(), + ) + + def save(self) -> None: + # Serves the CTO / database administrators + db.execute("INSERT INTO employees ...", self._to_dict()) + + def _get_regular_hours(self) -> float: + # Shared by calculate_pay and report_hours -- dangerous coupling + return min(self.hours_worked, 40) + + def _get_overtime_hours(self) -> float: + return max(self.hours_worked - 40, 0) +``` + +**The problem:** Three actors (CFO, COO, CTO) all have reasons to change this class. When the CFO wants to change how overtime is calculated, the shared `_get_regular_hours` method might be modified in a way that breaks the COO's reports. + +### SRP-Compliant Design + +```python +class PayCalculator: + """Serves the CFO / accounting""" + def calculate_pay(self, employee_data: EmployeeData) -> Money: + regular = min(employee_data.hours_worked, 40) + overtime = max(employee_data.hours_worked - 40, 0) + return regular * employee_data.rate + overtime * employee_data.rate * 1.5 + +class HoursReporter: + """Serves the COO / operations""" + def report_hours(self, employee_data: EmployeeData) -> HoursReport: + return HoursReport( + regular=min(employee_data.hours_worked, 40), + overtime=max(employee_data.hours_worked - 40, 0), + ) + +class EmployeeRepository: + """Serves the CTO / database administration""" + def save(self, employee_data: EmployeeData) -> None: + self._db.execute("INSERT INTO employees ...", employee_data.to_dict()) +``` + +Each class now serves one actor. Changes requested by the CFO only affect `PayCalculator`. The COO's changes only affect `HoursReporter`. They can evolve independently. + +### SRP Indicators + +| Indicator | Likely Violation | +|-----------|-----------------| +| Class has methods serving different departments/teams | Multiple actors | +| "And" in the class name (`OrderValidatorAndNotifier`) | Multiple responsibilities | +| Class changes frequently for unrelated reasons | Multiple change drivers | +| Merge conflicts from unrelated feature branches | Multiple actors modifying same class | +| Unit tests require many unrelated mocks | Class does too many things | + +## OCP: The Open-Closed Principle + +**"A software artifact should be open for extension but closed for modification."** + +You should be able to extend the behavior of a system without modifying existing code. New features are added by writing new code, not by changing old code. + +### The Strategy Pattern Approach + +```python +# Closed for modification -- this code doesn't change when new shipping methods are added +class OrderService: + def __init__(self, shipping_strategy: ShippingStrategy): + self._shipping = shipping_strategy + + def calculate_total(self, order: Order) -> Money: + subtotal = order.subtotal() + shipping = self._shipping.calculate(order) + return subtotal + shipping + +# Open for extension -- add new shipping methods without touching OrderService +class ShippingStrategy(ABC): + @abstractmethod + def calculate(self, order: Order) -> Money: + pass + +class StandardShipping(ShippingStrategy): + def calculate(self, order: Order) -> Money: + return Money("5.99") + +class ExpressShipping(ShippingStrategy): + def calculate(self, order: Order) -> Money: + return Money("14.99") + +# New shipping method -- no existing code modified +class FreeShippingOver50(ShippingStrategy): + def calculate(self, order: Order) -> Money: + return Money("0.00") if order.subtotal() >= Money("50.00") else Money("5.99") +``` + +### Common OCP Violations + +```python +# VIOLATION: Adding a new payment method requires modifying this function +def process_payment(method: str, amount: Money) -> PaymentResult: + if method == "credit_card": + return charge_credit_card(amount) + elif method == "paypal": + return charge_paypal(amount) + elif method == "apple_pay": # New method = new elif = modification + return charge_apple_pay(amount) +``` + +**Fix with OCP:** + +```python +class PaymentProcessor(ABC): + @abstractmethod + def process(self, amount: Money) -> PaymentResult: + pass + +class CreditCardProcessor(PaymentProcessor): + def process(self, amount: Money) -> PaymentResult: + return self._gateway.charge(amount) + +# Adding Apple Pay = new class, no modification to existing code +class ApplePayProcessor(PaymentProcessor): + def process(self, amount: Money) -> PaymentResult: + return self._apple_client.charge(amount) +``` + +### OCP in Clean Architecture + +OCP is foundational to the concentric circles model. The inner circles (entities, use cases) are closed for modification. The outer circles (adapters, frameworks) are open for extension. You extend the system by adding new adapters, new controllers, new gateways -- not by modifying business rules. + +## LSP: The Liskov Substitution Principle + +**"Subtypes must be substitutable for their base types."** + +If S is a subtype of T, then objects of type T may be replaced with objects of type S without altering the correctness of the program. + +### The Classic Violation: Square/Rectangle + +```python +class Rectangle: + def __init__(self, width: float, height: float): + self._width = width + self._height = height + + def set_width(self, w: float) -> None: + self._width = w + + def set_height(self, h: float) -> None: + self._height = h + + def area(self) -> float: + return self._width * self._height + +class Square(Rectangle): + def set_width(self, w: float) -> None: + self._width = w + self._height = w # Must keep square invariant + + def set_height(self, h: float) -> None: + self._width = h # Must keep square invariant + self._height = h +``` + +**The problem:** Code that works correctly with `Rectangle` breaks with `Square`: + +```python +def test_area(rect: Rectangle): + rect.set_width(5) + rect.set_height(4) + assert rect.area() == 20 # Fails for Square! Area is 16 because set_height changed width +``` + +`Square` is NOT substitutable for `Rectangle`. LSP is violated. + +### LSP in Practice + +| Violation Pattern | Why It Breaks | Fix | +|-------------------|--------------|-----| +| Subclass throws unexpected exceptions | Callers don't handle exceptions they didn't expect from the base type | Subclass should honor the base type's exception contract | +| Subclass ignores methods (no-op override) | Callers rely on the method doing something | The class hierarchy is wrong; use composition or a different abstraction | +| Subclass strengthens preconditions | Callers that work with base type fail with subtype | Subtypes may weaken preconditions, never strengthen them | +| Subclass weakens postconditions | Callers expect guarantees the subtype doesn't provide | Subtypes may strengthen postconditions, never weaken them | + +### LSP and Interfaces in Clean Architecture + +LSP applies to interfaces as well as inheritance hierarchies. When a Use Case depends on `OrderRepository`, every implementation (`PostgresOrderRepository`, `MongoOrderRepository`, `InMemoryOrderRepository`) must behave consistently: + +- `save()` must persist the entity (or fail with a defined exception) +- `find_by_id()` must return the entity if it exists or `None` if not +- No implementation should silently drop data, return stale data, or throw exceptions not defined in the interface contract + +## ISP: The Interface Segregation Principle + +**"No client should be forced to depend on methods it does not use."** + +Fat interfaces create unnecessary coupling. When a client depends on an interface with methods it doesn't use, it becomes vulnerable to changes in those unused methods. + +### Classic Violation + +```python +class MultiFunctionDevice(ABC): + @abstractmethod + def print_document(self, doc: Document) -> None: pass + + @abstractmethod + def scan_document(self) -> Image: pass + + @abstractmethod + def fax_document(self, doc: Document, number: str) -> None: pass + + @abstractmethod + def staple_pages(self, pages: list[Page]) -> None: pass + +# A simple printer must implement fax and staple -- methods it can't fulfill +class SimplePrinter(MultiFunctionDevice): + def print_document(self, doc: Document) -> None: + # Actually prints + ... + + def scan_document(self) -> Image: + raise NotSupportedError() # ISP violation! + + def fax_document(self, doc: Document, number: str) -> None: + raise NotSupportedError() # ISP violation! + + def staple_pages(self, pages: list[Page]) -> None: + raise NotSupportedError() # ISP violation! +``` + +### ISP-Compliant Design + +```python +class Printer(ABC): + @abstractmethod + def print_document(self, doc: Document) -> None: pass + +class Scanner(ABC): + @abstractmethod + def scan_document(self) -> Image: pass + +class FaxMachine(ABC): + @abstractmethod + def fax_document(self, doc: Document, number: str) -> None: pass + +# Simple printer only implements what it can do +class SimplePrinter(Printer): + def print_document(self, doc: Document) -> None: + ... + +# Multi-function device implements all relevant interfaces +class OfficePrinter(Printer, Scanner, FaxMachine): + def print_document(self, doc: Document) -> None: ... + def scan_document(self) -> Image: ... + def fax_document(self, doc: Document, number: str) -> None: ... +``` + +### ISP in Clean Architecture + +ISP directly supports the Dependency Rule. Use Cases define narrow, focused input and output port interfaces. Each adapter implements only the interfaces it needs: + +```python +# Focused interfaces (ISP-compliant) +class OrderReader(ABC): + @abstractmethod + def find_by_id(self, order_id: str) -> Order | None: pass + +class OrderWriter(ABC): + @abstractmethod + def save(self, order: Order) -> None: pass + +class OrderSearcher(ABC): + @abstractmethod + def search(self, criteria: SearchCriteria) -> list[Order]: pass + +# Use Case that only reads doesn't depend on write methods +class GetOrderDetailsInteractor: + def __init__(self, reader: OrderReader): # Only depends on reading + self._reader = reader +``` + +## DIP: The Dependency Inversion Principle + +**"High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions."** + +DIP is the mechanism that makes the Dependency Rule work. It inverts the natural direction of source code dependencies so that the volatile, concrete, outer-circle code depends on the stable, abstract, inner-circle code. + +### Without DIP (Natural Dependencies) + +``` +OrderService --> PostgresDatabase + (high-level) (low-level) +``` + +The high-level policy (OrderService) depends on the low-level detail (PostgresDatabase). Changing the database means changing the service. + +### With DIP (Inverted Dependencies) + +``` +OrderService --> OrderRepository (interface) + ^ + | + PostgresOrderRepository +``` + +Both the high-level service and the low-level database adapter depend on the abstraction (OrderRepository). The abstraction is defined by the high-level module, not by the low-level module. + +### DIP Implementation Pattern + +```python +# HIGH-LEVEL MODULE defines the abstraction +class OrderRepository(ABC): + """Defined in the Use Case circle. The high-level policy dictates what it needs.""" + @abstractmethod + def save(self, order: Order) -> None: pass + + @abstractmethod + def find_by_id(self, order_id: str) -> Order | None: pass + +# HIGH-LEVEL MODULE uses the abstraction +class PlaceOrderInteractor: + def __init__(self, repo: OrderRepository): # Depends on abstraction + self._repo = repo + + def execute(self, request: PlaceOrderRequest) -> None: + order = Order.create(request.items, request.customer_id) + self._repo.save(order) # Calls abstraction + +# LOW-LEVEL MODULE implements the abstraction +class PostgresOrderRepository(OrderRepository): # Depends on abstraction + def __init__(self, pool): + self._pool = pool + + def save(self, order: Order) -> None: + # SQL details here -- low-level + ... + +# COMPOSITION ROOT wires them together +def main(): + pool = create_pool(DATABASE_URL) + repo = PostgresOrderRepository(pool) + interactor = PlaceOrderInteractor(repo) # Inject concrete into abstract slot +``` + +### DIP: Who Owns the Interface? + +This is the critical insight: **the interface belongs to the high-level module, not the low-level module.** + +| Ownership | Meaning | Result | +|-----------|---------|--------| +| Interface owned by high-level module | The Use Case defines what it needs | Low-level module adapts to high-level needs | +| Interface owned by low-level module | The database defines its capabilities | High-level module must adapt to database -- dependency NOT inverted | + +When the Use Case defines `OrderRepository`, it specifies methods like `save(order)` and `find_by_id(id)` -- business-oriented operations. The database adapter must conform to this business-oriented interface. + +When the database adapter defines the interface, it specifies methods like `execute_query(sql)` and `fetch_rows(table)` -- technology-oriented operations. The Use Case must conform to the database's way of thinking. This is the natural dependency direction, NOT inverted. + +### Common DIP Violations + +| Violation | Example | Fix | +|-----------|---------|-----| +| Importing concrete classes in high-level modules | `from stripe import StripeClient` in Use Case | Define `PaymentGateway` interface in Use Case; implement with Stripe in adapter | +| Using static/global factory methods | `Database.get_instance()` in Use Case | Inject repository through constructor | +| Depending on framework types in domain | `@Autowired` on domain class | Use plain constructor injection; wire in Main | +| Low-level module defines the interface | `IStripeGateway` lives in the Stripe adapter package | Move interface to Use Case package; rename to `PaymentGateway` | +| New operator in high-level code | `repo = PostgresRepository()` inside Use Case | Inject through constructor; instantiate in Main | + +### DIP and Clean Architecture + +DIP is the engine of Clean Architecture. Every boundary in the concentric circles model is maintained through dependency inversion: + +- **Use Case to Database:** `OrderRepository` interface (defined by Use Case) inverts the dependency so the database adapter depends inward +- **Use Case to Web:** `PlaceOrderOutput` interface (defined by Use Case) inverts the dependency so the presenter depends inward +- **Use Case to External Service:** `EmailService` interface (defined by Use Case) inverts the dependency so the email adapter depends inward + +Without DIP, inner circles would depend on outer circles, the Dependency Rule would be violated, and the architecture would collapse into a ball of mud. diff --git a/.agents/skills/clean-code/SKILL.md b/.agents/skills/clean-code/SKILL.md new file mode 100644 index 00000000..84a8a50f --- /dev/null +++ b/.agents/skills/clean-code/SKILL.md @@ -0,0 +1,222 @@ +--- +name: clean-code +description: 'Write readable, maintainable code through disciplined naming, small functions, and clean error handling. Use when the user mentions "clean up this code", "this function is too long", "code smells", "naming conventions", "boy scout rule", "single responsibility", or "unit test quality". Also trigger when reviewing a pull request for readability, untangling a messy function, debating comment styles, or improving error-handling patterns. Covers SRP, comment discipline, formatting, and unit testing. For refactoring techniques, see refactoring-patterns. For architecture and dependency rules, see clean-architecture.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Clean Code Framework + +A disciplined approach to writing code that communicates intent, minimizes surprises, and welcomes change. Apply these principles when writing new code, reviewing pull requests, refactoring legacy systems, or advising on code quality. + +## Core Principle + +**Code is read far more often than it is written — optimize for the reader.** The read-to-write ratio is well over 10:1, so every naming choice, function boundary, and formatting decision either adds clarity or adds cost. Clean code reads like well-written prose: names reveal intent, functions tell a story one step at a time, and the Boy Scout Rule applies — always leave the code cleaner than you found it. + +## Scoring + +**Goal: 10/10.** Rate any code 0-10 against the principles below. Report the current score and the specific improvements needed to reach 10/10. + +- **9-10:** Names reveal intent, functions are small and focused, error handling is consistent, tests are clean and comprehensive +- **7-8:** Mostly clean with minor naming ambiguities or a few long functions; tests may lack edge cases +- **5-6:** Mixed — good patterns alongside unclear names, duplicated logic, or inconsistent error handling +- **3-4:** Long multi-purpose functions, misleading names, poor or missing tests +- **1-2:** Nearly unreadable — magic numbers, cryptic abbreviations, no structure, no tests + +## The Clean Code Framework + +Six disciplines for writing code that communicates clearly and adapts to change: + +### 1. Meaningful Names + +**Core concept:** Names should reveal intent, avoid disinformation, and make the code read like prose. If a name requires a comment to explain it, the name is wrong. + +**Why it works:** Names are the most pervasive form of documentation — a well-chosen name eliminates the need to read the implementation; a poor one forces every reader to reverse-engineer intent. + +**Key insights:** +- A name should answer why it exists, what it does, and how it is used +- No encodings, prefixes, or type information (no Hungarian notation); single letters only for tiny-scope loop counters +- Classes are nouns; methods are verbs +- One word per concept: don't mix `fetch`, `retrieve`, and `get` +- Longer scope demands a longer, more descriptive name +- Rename freely — IDEs make it trivial + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Variables** | Intention-revealing | `elapsedTimeInDays` not `d` | +| **Booleans** | Predicate phrasing | `isActive`, `hasPermission`, `canEdit` | +| **Functions** | Verb + noun | `calculateMonthlyRevenue()` not `calc()` | +| **Classes** | Noun naming the responsibility | `InvoiceGenerator` not `InvoiceManager` | + +See [references/naming-conventions.md](references/naming-conventions.md) when renaming or reviewing names — per-language conventions, pronounceable/searchable tables, and before/after examples. + +### 2. Functions + +**Core concept:** Functions should be small, do one thing, and do it well — ideally 4-6 lines, zero to two arguments, one level of abstraction. + +**Why it works:** Small single-purpose functions are easy to name, understand, test, and reuse; long functions hide bugs, resist testing, and accumulate responsibilities. + +**Key insights:** +- Step-Down Rule: code reads top-down, each function calling the next level of abstraction +- Argument count: zero best, one fine, two acceptable, three+ requires justification +- Flag arguments are a smell — the function does two things; split it +- Command-Query Separation: change state or return a value, never both +- Extract till you drop: if you can pull out a named function, do it +- No hidden side effects — the name must tell the whole truth + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Long function** | Extract named steps | `validateInput(); transformData(); saveRecord();` | +| **Flag argument** | Split into two functions | `renderForPrint()` / `renderForScreen()` not `render(isPrint)` | +| **Error cases** | Guard clauses at top | Early return for errors, single happy path | +| **Many arguments** | Introduce parameter object | `new DateRange(start, end)` not `report(start, end, format, locale)` | +| **Side effects** | Make effects explicit | `checkPassword()` that starts a session → rename or separate | + +See [references/functions-and-methods.md](references/functions-and-methods.md) when splitting a long function — argument-count rules, command-query separation, and step-down worked examples. + +### 3. Comments and Formatting + +**Core concept:** A comment is a failure to express yourself in code. When comments are necessary, they explain *why*, never *what*. Formatting creates the visual structure that makes code scannable. + +**Why it works:** Comments rot — code changes but comments often don't, creating documentation worse than none. Clean formatting lets developers scan code like a newspaper: headlines first, details on demand. + +**Key insights:** +- The best comment is a well-named extracted function +- Acceptable: legal headers, TODOs, public API docs, genuine "why" explanations +- Commented-out code and journal comments: delete — version control remembers +- Vertical openness between concepts; vertical density within them; declare variables near usage +- Newspaper metaphor: high-level functions at the top of the file, details below + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Explaining "what"** | Replace with better name | `// check if eligible` → `isEligible()` | +| **Explaining "why"** | Keep as comment | `// RFC 7231 requires this header for proxies` | +| **Commented-out code** | Delete it | Trust version control | +| **Team formatting** | Decide once, automate | Prettier, Black, gofmt | + +See [references/comments-formatting.md](references/comments-formatting.md) when deciding whether a comment earns its place — good-vs-bad comment catalog and vertical-formatting rules. + +### 4. Error Handling + +**Core concept:** Error handling is a separate concern from business logic. Use exceptions rather than return codes, provide context with every exception, and never return or pass null. + +**Why it works:** Return codes clutter the happy path with checks; exceptions separate the two cleanly. Returning null forces null checks on every caller, and one missing check crashes far from the source. + +**Key insights:** +- Write the try-catch first — it defines a transaction boundary +- Prefer unchecked exceptions — checked ones violate the Open/Closed Principle +- Define exception classes by the caller's needs, not the failure type +- Don't return null (use empty collections, Optional, or throw); don't pass null either +- Special Case / Null Object pattern: return an object with default behavior instead of null + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Null returns** | Empty collection or Optional | `return Collections.emptyList()` not `return null` | +| **Error codes** | Replace with exceptions | `throw new InsufficientFundsException(balance, amount)` | +| **Third-party APIs** | Wrap with adapter | `PortfolioService` wraps the vendor API, translates its exceptions | +| **Special cases** | Null Object pattern | `GuestUser` with default behavior instead of null checks | +| **Context in errors** | Include operation + state | `"Failed to save invoice #1234 for customer 'Acme'"` | + +See [references/error-handling.md](references/error-handling.md) when designing exception or null strategy — Special Case pattern and third-party-API wrapping examples. + +### 5. Unit Testing + +**Core concept:** Tests are first-class code, kept clean with the same discipline as production code. Dirty tests are worse than no tests — they become a liability that slows every change. + +**Why it works:** Clean tests are executable documentation and a safety net for refactoring; dirty tests make every modification a fight through incomprehensible test code. + +**Key insights:** +- Three Laws of TDD: write a failing test first; only enough test to fail; only enough code to pass +- One concept per test — one logical assertion, not necessarily one assert +- F.I.R.S.T.: Fast, Independent, Repeatable, Self-validating, Timely +- Build a domain-specific testing language: helpers that read like a DSL +- Refactor test code as readily as production code + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Test structure** | Arrange-Act-Assert | Setup, execute, verify — clearly separated | +| **Test naming** | Scenario + expected behavior | `shouldRejectExpiredToken` not `test1` | +| **Shared setup** | Builder/factory helpers | `aUser().withRole(ADMIN).build()` | +| **Flaky tests** | Remove external dependencies | Mock time, network, file system | + +See [references/testing-principles.md](references/testing-principles.md) when writing or cleaning tests — TDD laws, F.I.R.S.T. expanded, and clean-test patterns. + +### 6. Code Smells and Heuristics + +**Core concept:** Smells are surface indicators of deeper design problems — learn to recognize them quickly and apply targeted refactorings instead of vague "cleanup". + +**Why it works:** Smells are heuristics that point toward likely problems without deep analysis, turning code review instinct into specific, repeatable moves. + +**Key insights:** +- Function smells: too many arguments, output arguments, flag arguments, dead functions +- General smells: duplication, wrong level of abstraction, feature envy, magic numbers +- Test smells: insufficient coverage, skipped tests, untested boundary conditions and failure paths +- Refactor in small, tested steps — never refactor and add features simultaneously +- Boy Scout Rule: leave the code cleaner than you found it + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Duplication** | Extract shared logic | Common validation → `validateEmail()` helper | +| **Feature envy** | Move method to the data's class | `order.calculateTotal()` not `calculator.total(order)` | +| **Dead code** | Delete it | Remove unused functions, unreachable branches | +| **Magic numbers** | Named constants | `MAX_LOGIN_ATTEMPTS = 5` not bare `5` | +| **Shotgun surgery** | Consolidate related changes | Group scattered logic into a single module | + +See [references/code-smells.md](references/code-smells.md) when a smell is hard to name — the full catalog by category, each paired with its targeted refactoring. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|------| +| **Abbreviating names** | Saves seconds writing, costs hours reading | Full descriptive names; IDEs autocomplete | +| **"Clever" one-liners** | Impressive to write, impossible to debug | Expand into readable named steps | +| **Comments instead of refactoring** | Comments rot; code is the truth | Extract a well-named function instead | +| **Catching generic exceptions** | Swallows bugs along with expected errors | Catch specific exceptions; let the rest propagate | +| **No tests for error paths** | Happy path works, edge cases crash | Test every branch, boundary, and failure mode | +| **Premature optimization** | Obscures intent for marginal gains | Clean first; optimize measured bottlenecks | +| **God classes** | One 2000-line class does everything | Apply SRP — split by responsibility | +| **Refactoring without tests** | No safety net for regressions | Write characterization tests first | +| **Inconsistent conventions** | Every file feels like a different codebase | Agree on style; enforce with linters and formatters | +| **Returning null everywhere** | Null checks spread like a virus | Optional, empty collections, or Null Object | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Can you understand each function without reading its body? | Names don't reveal intent | Rename to describe what it does | +| Are all functions under 20 lines? | Functions do too many things | Extract sub-operations into named helpers | +| Zero commented-out code blocks? | Dead code creating confusion | Delete — version control has history | +| Is error handling separate from business logic? | Try-catch clutters the main flow | Extract handlers; exceptions over return codes | +| Does every class have a single responsibility? | Classes accumulate unrelated duties | Split into focused, well-named classes | +| Is there a test for every public method? | No safety net for changes | Add tests before changing further | +| Are test names descriptive of behavior? | Failures are hard to interpret | Rename to `shouldDoXWhenY` | +| Is duplication below 3 occurrences? | Copy-paste spreading bugs | Extract shared logic (§6) | +| Are magic numbers named constants? | Intent hidden behind raw values | Name the constant (§6) | +| Do all tests run in under 10 seconds? | Slow tests don't get run | Mock external deps; split integration tests | + +## Further Reading + +Based on Robert C. Martin's seminal guide to software craftsmanship: + +- [*"Clean Code: A Handbook of Agile Software Craftsmanship"*](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882?tag=wondelai00-20) by Robert C. Martin +- [*"The Clean Coder: A Code of Conduct for Professional Programmers"*](https://www.amazon.com/Clean-Coder-Conduct-Professional-Programmers/dp/0137081073?tag=wondelai00-20) by Robert C. Martin +- [*"Clean Architecture: A Craftsman's Guide to Software Structure and Design"*](https://www.amazon.com/Clean-Architecture-Craftsmans-Software-Structure/dp/0134494164?tag=wondelai00-20) by Robert C. Martin +- [*"Refactoring: Improving the Design of Existing Code"*](https://www.amazon.com/Refactoring-Improving-Existing-Addison-Wesley-Signature/dp/0134757599?tag=wondelai00-20) by Martin Fowler + +## About the Author + +**Robert C. Martin ("Uncle Bob")** has been programming since 1970, co-authored the Agile Manifesto, and founded Uncle Bob Consulting and Clean Coders. His books — *Clean Code*, *The Clean Coder*, *Clean Architecture*, and *Clean Agile* — shaped how a generation of developers think about code quality, and his core stance is that the only way to go fast is to go well. diff --git a/.agents/skills/clean-code/references/code-smells.md b/.agents/skills/clean-code/references/code-smells.md new file mode 100644 index 00000000..c7df5f63 --- /dev/null +++ b/.agents/skills/clean-code/references/code-smells.md @@ -0,0 +1,494 @@ +# Code Smells and Heuristics + +Comprehensive catalog of code smells organized by category, with identification criteria and targeted refactorings. Based on Robert C. Martin's *Clean Code*, Chapter 17. + + +## Table of Contents +1. [What Is a Code Smell?](#what-is-a-code-smell) +2. [Comment Smells](#comment-smells) +3. [Environment Smells](#environment-smells) +4. [Function Smells](#function-smells) +5. [General Smells](#general-smells) +6. [Naming Smells](#naming-smells) +7. [Test Smells](#test-smells) +8. [Smell Detection Quick Reference](#smell-detection-quick-reference) + +--- + +## What Is a Code Smell? + +A code smell is a surface indication that usually corresponds to a deeper problem in the system. Smells are not bugs -- the code works. But they suggest fragility, rigidity, or unnecessary complexity that will cause problems as the codebase evolves. Learn to recognize smells quickly and you'll know where to focus refactoring effort. + +--- + +## Comment Smells + +Comments that indicate problems in the code: + +### C1: Inappropriate Information + +Comments that hold information better kept in other systems. + +| Information type | Where it belongs | Not in comments | +|-----------------|-----------------|-----------------| +| Change history | Git log | Not `// Changed by John on 2024-01-15` | +| Author attribution | `git blame` | Not `// Author: john@company.com` | +| Issue tracking | Jira/GitHub Issues | Not `// Fixes bug #1234` (use commit message) | +| Build instructions | README or Makefile | Not `// Run with -Xmx512m flag` | + +**Comments should only contain technical notes about the code itself.** + +### C2: Obsolete Comments + +Comments that have grown old and are no longer accurate. Code evolves; comments don't always follow. + +```java +// BAD: This comment is now a lie +// Returns the total price including 5% tax +public double getTotal() { + return subtotal * 1.08; // Tax rate changed to 8%, comment not updated +} +``` + +**Fix:** Delete the comment. If the information is important, express it in the code: + +```java +private static final double TAX_RATE = 0.08; + +public double getTotal() { + return subtotal * (1 + TAX_RATE); +} +``` + +### C3: Redundant Comments + +Comments that describe something that adequately describes itself. + +```java +i++; // increment i +``` + +If the code is clear, the comment is noise. If the code is not clear, fix the code. + +### C4: Poorly Written Comments + +If you're going to write a comment, take the time to write it well. Don't ramble. Don't state the obvious. Use correct grammar and punctuation. Be brief and precise. + +### C5: Commented-Out Code + +```python +# result = old_algorithm(data) +# if result > threshold: +# notify_admin(result) +result = new_algorithm(data) +``` + +Commented-out code rots. Others are afraid to delete it ("maybe someone needs it?"). It accumulates. **Delete it.** Version control is your safety net. + +--- + +## Environment Smells + +### E1: Build Requires More Than One Step + +You should be able to build the entire system with a single command. + +```bash +# GOOD: One command +make build +# or +npm run build +# or +./gradlew build +``` + +If building requires checkout, install, configure, set env vars, download dependencies separately, the build is fragile and developers will avoid running it. + +### E2: Tests Require More Than One Step + +You should be able to run all the tests with a single command. + +```bash +# GOOD: One command +make test +# or +npm test +# or +pytest +``` + +If running tests requires starting databases, setting up fixtures manually, or running scripts in a specific order, developers won't run them. + +--- + +## Function Smells + +### F1: Too Many Arguments + +More than three arguments is a smell. Arguments are hard to understand, hard to remember, and hard to test (every combination of arguments is a test case). + +| Arguments | Assessment | Action | +|-----------|------------|--------| +| 0 | Ideal | Keep as is | +| 1 | Good | Common and clear | +| 2 | Acceptable | Ensure natural pairing | +| 3 | Questionable | Can any be grouped into an object? | +| 4+ | Refactor | Introduce parameter object or builder | + +**Refactoring:** +```python +# BAD: Too many arguments +def create_user(first_name, last_name, email, phone, address, city, state, zip_code): + ... + +# GOOD: Parameter object +def create_user(personal_info: PersonalInfo, address: Address): + ... +``` + +### F2: Output Arguments + +Arguments that are modified by the function are confusing. Is the argument input or output? + +```java +// BAD: Is report being read or modified? +appendFooter(report); + +// GOOD: Method on the object being modified +report.appendFooter(); +``` + +In general, output arguments should be avoided. If a function must change the state of something, have it change the state of the object it is called on. + +### F3: Flag Arguments + +Boolean arguments loudly declare that the function does two things. + +```python +# BAD: Flag argument +def create_account(user_data, is_admin): + if is_admin: + # 15 lines of admin setup + else: + # 15 lines of regular setup + +# GOOD: Separate functions +def create_admin_account(user_data): + ... + +def create_user_account(user_data): + ... +``` + +### F4: Dead Functions + +Functions that are never called should be deleted. Don't keep them around "just in case." Your version control system remembers them if you ever need them back. + +**How to find dead functions:** +- IDE "Find Usages" reports zero callers +- Static analysis tools flag unreachable code +- Code coverage reports show 0% coverage +- Search for the function name across the codebase + +--- + +## General Smells + +### G1: Multiple Languages in One Source File + +A single source file should contain one language. Mixing HTML, JavaScript, CSS, SQL, and server-side code in one file creates confusion. + +| Acceptable | Problematic | +|------------|-------------| +| JavaScript in a `.js` file | SQL strings embedded in Java | +| CSS in a `.css` file | HTML templates inline in Python | +| SQL in a `.sql` migration file | CSS-in-JS with complex logic | + +**Minimize** the extent and number of extra languages in source files. + +### G2: Obvious Behavior Is Not Implemented + +When the obvious behavior of a function is not implemented, readers lose trust in the author. + +```python +# SURPRISING: dayOfWeek("Monday") should obviously return Day.MONDAY +def day_of_week(name): + days = {"Monday": 1, "Tuesday": 2, ...} # Missing "MONDAY", "monday" + return days[name] # Crashes on case variants +``` + +Follow the Principle of Least Surprise. Users and callers should not be surprised by what a function does. + +### G3: Incorrect Behavior at the Boundaries + +Don't rely on your intuition for boundary cases. **Write tests for every boundary condition.** Things that commonly fail at boundaries: + +| Boundary | Common failure | +|----------|---------------| +| Empty input | NullPointerException, IndexOutOfBounds | +| Single element | Off-by-one in loops | +| Maximum capacity | Buffer overflow, performance cliff | +| Negative values | Unexpected results in calculations | +| Unicode | Encoding issues, wrong string length | +| Concurrent access | Race conditions, deadlocks | + +### G4: Overridden Safeties + +Turning off warnings, suppressing exceptions, or disabling tests is dangerous. + +```python +# BAD: Ignoring the warning doesn't fix the problem +@SuppressWarnings("unchecked") # Why is this unchecked? +warnings.filterwarnings("ignore") # What are we hiding? +@pytest.mark.skip("Flaky") # Fix it instead of skipping +``` + +Turning off compiler warnings or ignoring failing tests is like ignoring a check-engine light. + +### G5: Duplication (DRY Violations) + +Duplication is the single most important smell. Every instance represents a missed opportunity for abstraction. + +| Duplication type | How to find it | Refactoring | +|-----------------|----------------|-------------| +| **Exact clones** | Copy-paste detection tools | Extract shared function | +| **Structural clones** | Same algorithm, different data | Template Method or Strategy pattern | +| **Conditional chains** | Repeated `if/else` or `switch` | Polymorphism | +| **Cross-module** | Same logic in multiple modules | Extract shared library or module | + +**The Rule of Three:** First instance: just write it. Second instance: note the duplication. Third instance: refactor. + +### G6: Code at Wrong Level of Abstraction + +Functions and classes should operate at a single level of abstraction. Mixing high-level business logic with low-level implementation details creates confusion. + +```python +# BAD: Mixed abstraction levels +def process_order(order): + # High-level business logic + validate_order(order) + + # Suddenly low-level database details + connection = psycopg2.connect(host="db.example.com", port=5432) + cursor = connection.cursor() + cursor.execute("INSERT INTO orders ...") + connection.commit() + + # Back to high-level + send_confirmation(order) + +# GOOD: Consistent abstraction level +def process_order(order): + validate_order(order) + order_repository.save(order) + send_confirmation(order) +``` + +### G7: Feature Envy + +A method that uses more features of another class than its own class has "feature envy." It wants to be somewhere else. + +```python +# BAD: This method envies the Order class +class ReportGenerator: + def calculate_order_summary(self, order): + subtotal = sum(item.price * item.quantity for item in order.items) + tax = subtotal * order.tax_rate + shipping = order.weight * order.shipping_rate + return subtotal + tax + shipping + +# GOOD: Move the method to where the data lives +class Order: + def calculate_total(self): + subtotal = sum(item.price * item.quantity for item in self.items) + tax = subtotal * self.tax_rate + shipping = self.weight * self.shipping_rate + return subtotal + tax + shipping +``` + +### G8: Selector Arguments + +Arguments used to select behavior (not just booleans, but enums and strings too). + +```python +# BAD: Selector argument +def calculate(operation, a, b): + if operation == "add": return a + b + if operation == "subtract": return a - b + if operation == "multiply": return a * b + +# GOOD: Separate functions +def add(a, b): return a + b +def subtract(a, b): return a - b +def multiply(a, b): return a * b +``` + +### G9: Obscured Intent + +Code that is designed to be compact at the expense of clarity. + +```python +# BAD: What does this do? +def m(a):return sum(1 for c in a if c.s=='A'and c.d x.id)` | +| 5-line method | Short | `i`, `sum`, `item` | +| Class field | Medium | `retryCount`, `lastUpdate` | +| Module constant | Long | `MAX_CONNECTION_POOL_SIZE` | +| Global/public API | Very long | `DEFAULT_SESSION_TIMEOUT_MINUTES` | + +### N6: Avoid Encodings + +Don't use Hungarian notation, member prefixes, or interface prefixes. + +| Encoding | Example | Better | +|----------|---------|--------| +| Hungarian | `strName`, `iCount` | `name`, `count` | +| Member prefix | `m_name`, `_name` | `name` (context is the class) | +| Interface prefix | `IUserService` | `UserService` (implementations get suffix: `UserServiceImpl`) | +| Type suffix | `nameString` | `name` | + +--- + +## Test Smells + +### T1: Insufficient Tests + +A test suite should test everything that could possibly break. Test every condition, every boundary, every edge case. + +### T2: Using a Coverage Tool + +Code coverage tools report which lines are not tested. Use them as a guide, not a goal. 100% line coverage does not mean 100% correctness, but untested lines definitely contain potential bugs. + +### T3: Don't Skip Trivial Tests + +Trivial tests are easy to write and their documentary value is higher than the cost of writing them. + +### T4: An Ignored Test Is a Question About an Ambiguity + +If requirements are unclear, write the test with `@skip` and a note about what's uncertain. A skipped test is a question waiting to be answered. + +### T5: Test Boundary Conditions + +Boundaries are where bugs cluster. Test all edges: empty input, one element, max capacity, off-by-one, overflow. + +### T6: Exhaustively Test Near Bugs + +When you find a bug in a function, don't just fix it. Test the function exhaustively. Bugs tend to congregate -- if there's one, there are likely others nearby. + +### T7: Patterns of Failure Are Revealing + +If tests fail in a pattern (all tests with dates fail, all tests with unicode fail), the pattern reveals the nature of the bug. Use this diagnostic information. + +### T8: Test Coverage Patterns Can Be Revealing + +Look at which code is not covered. If a complex conditional has untested branches, those branches likely contain bugs. + +### T9: Tests Should Be Fast + +Slow tests don't get run. A test suite that takes 30 minutes will be run once a day at best. A suite that takes 10 seconds will be run after every change. + +--- + +## Smell Detection Quick Reference + +| Category | Key Smells | First Action | +|----------|-----------|--------------| +| **Comments** | Obsolete, redundant, commented-out code | Delete the comment; improve the code | +| **Environment** | Multi-step build or test | Script to single command | +| **Functions** | Too many args, flag args, dead functions | Extract object, split function, delete | +| **General** | Duplication, wrong abstraction level, feature envy | Extract, move, consolidate | +| **Names** | Ambiguous, wrong level, encoded | Rename to reveal intent | +| **Tests** | Insufficient, slow, skipped, no boundaries | Add tests, mock dependencies, fix or delete | + +**Remember:** Not every smell requires immediate action. Use professional judgment. A smell in frequently-changed code demands attention. A smell in stable code that never changes may not be worth the risk of refactoring. diff --git a/.agents/skills/clean-code/references/comments-formatting.md b/.agents/skills/clean-code/references/comments-formatting.md new file mode 100644 index 00000000..21c5ddea --- /dev/null +++ b/.agents/skills/clean-code/references/comments-formatting.md @@ -0,0 +1,405 @@ +# Comments and Formatting + +Comprehensive guide to comment discipline and code formatting. Based on Robert C. Martin's *Clean Code*, Chapters 4 and 5. + + +## Table of Contents +1. [The Truth About Comments](#the-truth-about-comments) +2. [Good Comments](#good-comments) +3. [Bad Comments](#bad-comments) +4. [Formatting](#formatting) +5. [When Comments Are Truly Necessary](#when-comments-are-truly-necessary) + +--- + +## The Truth About Comments + +**Don't comment bad code -- rewrite it.** Comments are, at best, a necessary evil. The proper use of comments is to compensate for our failure to express ourselves in code. Every time you write a comment, you should grimace and feel the failure of your ability of expression. + +Comments lie. Not always, and not intentionally, but too often. Code changes and evolves; comments don't always follow. The older a comment is and the farther it is from the code it describes, the more likely it is to be wrong. + +--- + +## Good Comments + +Not all comments are bad. Some are necessary and valuable. Here are the types worth writing: + +### Legal Comments + +Copyright and license headers mandated by corporate or legal standards. + +```java +// Copyright (c) 2024 Acme Corp. All rights reserved. +// Licensed under the Apache License, Version 2.0 +``` + +Keep them short. Reference a standard license file rather than embedding the full text. + +### Informative Comments + +Provide information that cannot be expressed in the code itself. + +```java +// Format: kk:mm:ss EEE, MMM dd, yyyy +Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*"); +``` + +Even here, a named constant or custom type could eliminate the need: `TIMESTAMP_PATTERN`. + +### Explanation of Intent + +Explain *why* a decision was made, not *what* the code does. + +```python +# We sort by creation date descending because the business requirement +# specifies that the most recently created items appear first in the +# dashboard, even though alphabetical would be more intuitive. +items.sort(key=lambda x: x.created_at, reverse=True) +``` + +This is valuable because the *what* is visible in the code, but the *why* would otherwise be lost. + +### Warning of Consequences + +Alert other developers about consequences that are not obvious. + +```java +// Don't run this test in CI -- it takes 45 minutes and requires +// a live connection to the production payment gateway +@Ignore("Long-running integration test requiring production access") +public void testLivePaymentGateway() { ... } +``` + +### TODO Comments + +Mark work that needs to be done but cannot be done right now. + +```python +# TODO(#1234): Replace with proper caching once Redis is provisioned +def get_user_preferences(user_id): + return db.query(f"SELECT * FROM preferences WHERE user_id = {user_id}") +``` + +**Rules for TODOs:** +- Include a ticket number or issue reference +- Scan and resolve them regularly (they are not permanent) +- Never use TODO as an excuse to leave broken code +- IDE/linter plugins can track and report outstanding TODOs + +### Amplification + +Emphasize the importance of something that might otherwise seem inconsequential. + +```java +String listItemContent = match.group(3).trim(); +// The trim is critically important. It removes trailing whitespace +// that would cause the item to be recognized as another list. +new ListItemWidget(this, listItemContent, this.level + 1); +``` + +--- + +## Bad Comments + +Most comments fall into these categories and should be eliminated: + +### Mumbling + +Comments written because "you should comment" rather than because they add value. + +```java +// The processor +private Processor processor; + +// Default constructor +public MyClass() { } +``` + +These say nothing. Delete them. + +### Redundant Comments + +Comments that take longer to read than the code they describe. + +```java +// Returns the day of the month +public int getDayOfMonth() { + return dayOfMonth; +} + +// Check if the employee is eligible for benefits +if (employee.isEligibleForBenefits()) { ... } +``` + +The code already says exactly this. The comment is noise. + +### Misleading Comments + +Comments that are subtly incorrect -- the most dangerous kind. + +```java +// Returns true if the user is active +public boolean isActive() { + return lastLoginDate != null && !isDeleted && subscriptionEndDate.isAfter(now()); +} +``` + +The comment says "active" means logged in before. The code checks three conditions. When the code changes and the comment doesn't, a future developer will be misled. + +### Mandated Comments + +Rules that require every function or variable to have a comment produce noise. + +```java +/** + * The name. + * @param name The name. + */ +public void setName(String name) { + this.name = name; +} +``` + +This adds no information. It's clutter that developers learn to ignore, which means they'll also ignore the few comments that actually matter. + +### Journal Comments + +Changelog entries at the top of files. + +```java +// 2024-01-15 - Added validation for email format +// 2024-01-20 - Fixed bug in email regex +// 2024-02-01 - Added support for international emails +``` + +This is what version control is for. `git log` and `git blame` provide this information with more accuracy and context. + +### Commented-Out Code + +```python +# user_cache = {} +# def get_cached_user(user_id): +# if user_id not in user_cache: +# user_cache[user_id] = db.get_user(user_id) +# return user_cache[user_id] + +def get_user(user_id): + return db.get_user(user_id) +``` + +Other developers are afraid to delete commented-out code because they think it must be there for a reason. It accumulates like barnacles. **Delete it.** Version control has perfect memory. + +### Noise Comments + +Comments that restate the obvious in a different form. + +```java +/** Default constructor */ +protected AnnualDateRule() { } + +/** The day of the month */ +private int dayOfMonth; + +/** Returns the day of the month + * @return the day of the month */ +public int getDayOfMonth() { return dayOfMonth; } +``` + +Every one of these is noise. They provide no information, train developers to ignore comments, and create a false sense of documentation thoroughness. + +### Position Markers and Banners + +```java +// ========== PRIVATE METHODS ========== +// --- Validation --- +// /////// Constructor /////// +``` + +If your file is so large that you need position markers, the file is too large. Extract classes instead of adding banners. + +### Closing Brace Comments + +```java +if (condition) { + while (running) { + for (item : items) { + // ... lots of code ... + } // for + } // while +} // if +``` + +If you need comments to track closing braces, your function is too long. Extract methods until the structure is obvious. + +### Attribution Comments + +```java +// Added by: john.smith@company.com +``` + +Version control tracks authorship more reliably. Use `git blame`. + +--- + +## Formatting + +### Why Formatting Matters + +Code formatting is about communication, and communication is the professional developer's first order of business. The formatting of your code communicates important information long after the original developer has moved on. + +### Vertical Formatting + +#### The Newspaper Metaphor + +Source files should be organized like a newspaper article: +- **Name** should be simple but explanatory (the headline) +- **Top** should provide high-level concepts and algorithms (the synopsis) +- **Bottom** should contain the lowest-level functions and details (the body) + +#### Vertical Openness Between Concepts + +Each group of related lines represents a complete thought. Separate thoughts with blank lines. + +```python +# GOOD: Blank lines separate concepts +import os +import sys + +from myapp.models import User +from myapp.services import EmailService + + +class UserRegistration: + + def __init__(self, email_service): + self.email_service = email_service + + def register(self, name, email): + user = User.create(name=name, email=email) + self.email_service.send_welcome(user) + return user +``` + +```python +# BAD: Everything runs together +import os +import sys +from myapp.models import User +from myapp.services import EmailService +class UserRegistration: + def __init__(self, email_service): + self.email_service = email_service + def register(self, name, email): + user = User.create(name=name, email=email) + self.email_service.send_welcome(user) + return user +``` + +#### Vertical Density + +Lines that are tightly related should appear close together vertically. Don't insert blank lines between closely related lines. + +```java +// BAD: Useless comments break vertical density +public class ReporterConfig { + + /** + * The class name of the reporter listener + */ + private String className; + + /** + * The properties of the reporter listener + */ + private List properties = new ArrayList<>(); +} + +// GOOD: Dense, related declarations together +public class ReporterConfig { + private String className; + private List properties = new ArrayList<>(); +} +``` + +#### Vertical Distance + +Closely related concepts should be kept vertically close to each other. Don't force the reader to hop around the file. + +**Rules:** +- **Local variables:** Declare at the top of the function or as close to first usage as practical +- **Instance variables:** Declare at the top of the class (everyone needs to know about them) +- **Dependent functions:** The caller should be above the callee, and they should be close +- **Conceptual affinity:** Functions that do similar things or operate on the same data should be near each other + +#### Vertical Ordering + +Function call dependencies should point downward: a function that is called should be below the function that calls it. This creates a nice flow from high-level to low-level, like reading a newspaper. + +### Horizontal Formatting + +#### Line Length + +**Keep lines short.** The old 80-character limit is a reasonable guideline. Modern screens can show more, but readability drops beyond 100-120 characters. Scrolling horizontally breaks the reader's flow. + +#### Horizontal Openness and Density + +Use whitespace to associate strongly related things and disassociate weakly related things. + +```java +// Spaces around assignment (weak association between sides) +int lineCount = countLines(); + +// No space between function name and parenthesis (strong association) +lineCount = countLines(); + +// Spaces around binary operators by precedence +return b*b - 4*a*c; // Multiplication is higher precedence, tighter +return (-b + determinant) / (2*a); +``` + +#### Indentation + +Indentation makes the scope hierarchy visible. Each level of nesting gets one indentation level. **Never break this rule, even for short `if` statements or tiny loops.** + +```java +// BAD: Collapsed scopes hide structure +if (condition) return true; + +// GOOD: Indentation preserved +if (condition) { + return true; +} +``` + +### Team Rules + +**A team should agree on a single formatting style and everyone should use it.** Individual style preferences must yield to the team standard. + +The best way to enforce team rules: + +| Approach | Tool examples | Benefit | +|----------|---------------|---------| +| **Automated formatter** | Prettier, Black, gofmt, rustfmt | Eliminates all style debates | +| **Linter with auto-fix** | ESLint, Pylint, RuboCop | Catches style and quality issues | +| **Pre-commit hooks** | Husky, pre-commit, lefthook | Prevents style violations from entering repo | +| **CI enforcement** | Format check in pipeline | Catches anything hooks miss | +| **EditorConfig** | `.editorconfig` file | Consistent settings across editors | + +**The best formatting rule:** Use an automated formatter and never think about formatting again. Time spent debating tabs versus spaces is time not spent writing clean code. + +--- + +## When Comments Are Truly Necessary + +Despite the general advice to minimize comments, certain situations genuinely require them: + +| Situation | Why code alone isn't enough | Example | +|-----------|---------------------------|---------| +| **Regulatory requirement** | Law/compliance requires documentation | HIPAA, SOX, GDPR compliance notes | +| **Non-obvious performance choice** | Algorithm choice isn't self-evident | "Using radix sort here because n > 10M and keys are bounded" | +| **External system quirk** | Workaround for third-party bug | "API returns 200 for errors; we check response body instead" | +| **Concurrency rationale** | Threading decisions need explanation | "Double-checked locking required here because..." | +| **Domain formula** | Mathematical formula from spec | "Amortization formula from IRS Publication 936" | +| **Public API contract** | Users cannot read implementation | Javadoc for library interfaces | + +The key: comments should explain *why*, never *what*. If you find yourself explaining *what* the code does, the code needs to be clearer, not the comment. diff --git a/.agents/skills/clean-code/references/error-handling.md b/.agents/skills/clean-code/references/error-handling.md new file mode 100644 index 00000000..c516e4dc --- /dev/null +++ b/.agents/skills/clean-code/references/error-handling.md @@ -0,0 +1,357 @@ +# Error Handling + +Comprehensive guide to writing clean error handling that keeps business logic readable. Based on Robert C. Martin's *Clean Code*, Chapter 7. + + +## Table of Contents +1. [The Core Problem](#the-core-problem) +2. [Use Exceptions, Not Return Codes](#use-exceptions-not-return-codes) +3. [Write Your Try-Catch-Finally Statement First](#write-your-try-catch-finally-statement-first) +4. [Use Unchecked Exceptions](#use-unchecked-exceptions) +5. [Provide Context with Exceptions](#provide-context-with-exceptions) +6. [Define Exception Classes in Terms of the Caller's Needs](#define-exception-classes-in-terms-of-the-callers-needs) +7. [Don't Return Null](#dont-return-null) +8. [Don't Pass Null](#dont-pass-null) +9. [Error Handling Patterns Summary](#error-handling-patterns-summary) +10. [Common Error Handling Anti-Patterns](#common-error-handling-anti-patterns) + +--- + +## The Core Problem + +Error handling is important, but if it obscures logic, it's wrong. Code that mixes business logic with error handling is hard to read, test, and maintain. The goal is to write code where the happy path reads cleanly and error handling is a separate, well-organized concern. + +--- + +## Use Exceptions, Not Return Codes + +Return codes force the caller to check immediately after the call, cluttering the calling code with error-checking logic. + +### Before: Return Codes + +```java +// BAD: Error checking clutters the logic +public class DeviceController { + public void sendShutDown() { + DeviceHandle handle = getHandle(DEV1); + if (handle != DeviceHandle.INVALID) { + DeviceRecord record = retrieveDeviceRecord(handle); + if (record.getStatus() != DEVICE_SUSPENDED) { + pauseDevice(handle); + clearDeviceWorkQueue(handle); + closeDevice(handle); + } else { + logger.log("Device suspended. Unable to shut down."); + } + } else { + logger.log("Invalid handle for: " + DEV1.toString()); + } + } +} +``` + +### After: Exceptions + +```java +// GOOD: Business logic is clean; errors handled separately +public class DeviceController { + public void sendShutDown() { + try { + tryToShutDown(); + } catch (DeviceShutDownError e) { + logger.log(e); + } + } + + private void tryToShutDown() throws DeviceShutDownError { + DeviceHandle handle = getHandle(DEV1); + DeviceRecord record = retrieveDeviceRecord(handle); + pauseDevice(handle); + clearDeviceWorkQueue(handle); + closeDevice(handle); + } +} +``` + +The business logic (shut down sequence) is now visible without wading through error checks. + +--- + +## Write Your Try-Catch-Finally Statement First + +Try-catch blocks define a scope within your program. The code in the `try` block can abort at any point and resume in the `catch`. This makes try blocks like transactions: the `catch` must leave the program in a consistent state. + +**Practice:** When writing code that could throw exceptions, start with the try-catch-finally. This helps you define what the caller can expect, regardless of what goes wrong. + +```python +# Start with the structure +def load_configuration(path): + try: + content = read_file(path) + config = parse_yaml(content) + validate_config(config) + return config + except FileNotFoundError: + return default_configuration() + except ParseError as e: + raise ConfigurationError(f"Invalid config at {path}: {e}") + finally: + log_config_load_attempt(path) +``` + +--- + +## Use Unchecked Exceptions + +Checked exceptions (Java's `throws` clause) violate the Open/Closed Principle. If you throw a checked exception from a low-level function, every function in the call chain between the throw and the catch must declare that exception. A single change at a low level forces signature changes all the way up. + +| Aspect | Checked exceptions | Unchecked exceptions | +|--------|-------------------|---------------------| +| **Coupling** | Every caller must declare or catch | Only relevant callers catch | +| **Encapsulation** | Low-level details leak to high-level | Abstraction layers maintained | +| **Refactoring** | Adding new exception type cascades changes | New exceptions don't affect existing callers | +| **When appropriate** | Critical library APIs where caller MUST handle | Application code, most library code | + +**In practice:** Use unchecked exceptions for application code. The cost of checked exceptions in dependency management outweighs their documentary benefit. + +--- + +## Provide Context with Exceptions + +Each exception should provide enough context to determine the source and location of the error. + +### What to Include + +| Context element | Why | Example | +|----------------|-----|---------| +| **Operation that failed** | Identifies what was attempted | "Failed to save invoice" | +| **Input that caused failure** | Enables reproduction | "Invoice #1234 for customer 'Acme'" | +| **Constraint that was violated** | Explains why it failed | "Total amount exceeds maximum of $1,000,000" | +| **Suggested recovery** | Helps caller respond | "Retry after 30 seconds" or "Check network connection" | + +### Implementation Pattern + +```python +# BAD: No context +raise ValueError("Invalid input") + +# BAD: Raw technical error +raise Exception(str(e)) + +# GOOD: Contextual error message +raise InvoiceValidationError( + f"Cannot create invoice for customer '{customer.name}': " + f"requested amount ${amount:.2f} exceeds credit limit " + f"of ${customer.credit_limit:.2f}" +) +``` + +### Custom Exception Classes + +```python +class OrderError(Exception): + """Base exception for order processing.""" + pass + +class InsufficientInventoryError(OrderError): + def __init__(self, product, requested, available): + self.product = product + self.requested = requested + self.available = available + super().__init__( + f"Cannot fulfill order: {product.name} has " + f"{available} units available, {requested} requested" + ) + +class PaymentDeclinedError(OrderError): + def __init__(self, order, reason): + self.order = order + self.reason = reason + super().__init__( + f"Payment declined for order #{order.id}: {reason}" + ) +``` + +--- + +## Define Exception Classes in Terms of the Caller's Needs + +When wrapping a third-party API, define exception classes based on how the caller will handle them, not based on the types of errors the API throws. + +### Before: Mirroring Third-Party Exceptions + +```java +// BAD: Caller must handle every possible vendor exception +try { + port.open(); +} catch (DeviceResponseException e) { + reportPortError(e); + logger.log("Device response exception", e); +} catch (ATM1212UnlockedException e) { + reportPortError(e); + logger.log("Unlock exception", e); +} catch (GMXError e) { + reportPortError(e); + logger.log("Device response exception"); +} +``` + +### After: Wrapping by Caller's Needs + +```java +// GOOD: Single exception class wraps all vendor exceptions +public class LocalPort { + private ACMEPort innerPort; + + public void open() { + try { + innerPort.open(); + } catch (DeviceResponseException e) { + throw new PortDeviceFailure(e); + } catch (ATM1212UnlockedException e) { + throw new PortDeviceFailure(e); + } catch (GMXError e) { + throw new PortDeviceFailure(e); + } + } +} + +// Caller only handles one type +try { + port.open(); +} catch (PortDeviceFailure e) { + reportError(e); + logger.log(e.getMessage(), e); +} +``` + +**Benefits of wrapping:** +- Minimizes dependencies on the third-party API +- Makes it easy to swap vendors +- Simplifies testing with mocks +- Keeps caller code clean + +--- + +## Don't Return Null + +Returning null from a method is an invitation for NullPointerExceptions. Every null return forces every caller to add a null check, and a single missed check crashes the application. + +### Alternatives to Returning Null + +| Instead of null | Return this | When | +|----------------|-------------|------| +| Null collection | Empty collection | Method returns a list, set, or map | +| Null string | Empty string `""` | Method returns text | +| Null object | Special case object | Object has default behavior | +| Null optional value | `Optional.empty()` | Value may legitimately be absent | +| Null on error | Throw exception | Absence indicates a problem | + +### The Special Case Pattern + +Instead of checking for null to handle a special case, create an object that handles the special case. + +```python +# BAD: Null checks everywhere +def get_expenses(employee): + expenses = db.find_expenses(employee) + if expenses is None: + return 0 + total = 0 + for expense in expenses: + if expense is not None: + total += expense.amount if expense.amount is not None else 0 + return total + +# GOOD: No null checks needed +def get_expenses(employee): + expenses = db.find_expenses(employee) # Returns empty list, never None + return sum(expense.amount for expense in expenses) +``` + +### Null Object Pattern + +```python +class RealUser: + def __init__(self, name, permissions): + self.name = name + self.permissions = permissions + + def has_permission(self, action): + return action in self.permissions + +class GuestUser: + """Null Object -- behaves like a user with no permissions.""" + name = "Guest" + permissions = frozenset() + + def has_permission(self, action): + return False + +def find_user(user_id): + user = db.find(user_id) + return user if user else GuestUser() + +# Caller never needs to check for null +user = find_user(request.user_id) +if user.has_permission("edit"): + allow_edit() +``` + +--- + +## Don't Pass Null + +Returning null is bad. Passing null is worse. When you pass null as an argument, you are creating a requirement for the callee to check for null, and if they don't, you get a runtime error. + +```java +// BAD: What should this do with null? +public double calculateMetric(Point p1, Point p2) { + return Math.sqrt( + Math.pow(p2.x - p1.x, 2) + Math.pow(p2.y - p1.y, 2) + ); +} + +// If someone calls calculateMetric(null, new Point(1, 2)) -- NullPointerException + +// GOOD: Fail fast with clear message +public double calculateMetric(Point p1, Point p2) { + Objects.requireNonNull(p1, "p1 must not be null"); + Objects.requireNonNull(p2, "p2 must not be null"); + return Math.sqrt( + Math.pow(p2.x - p1.x, 2) + Math.pow(p2.y - p1.y, 2) + ); +} +``` + +**The best policy:** Forbid passing null by default. Use static analysis tools (`@NonNull`, `@Nullable` annotations) and code review to enforce this. + +--- + +## Error Handling Patterns Summary + +| Pattern | When to use | Benefit | +|---------|-------------|---------| +| **Try-catch-finally first** | Any code that could fail | Defines transaction boundary upfront | +| **Wrap third-party APIs** | Calling external libraries | Isolates vendor dependencies | +| **Special Case pattern** | Default behavior for missing data | Eliminates null/error checks in callers | +| **Null Object pattern** | Polymorphic default behavior | No null checks in calling code | +| **Guard clauses** | Input validation | Fail fast with clear messages | +| **Custom exception hierarchy** | Domain-specific errors | Caller handles by intent, not implementation | +| **Exception with context** | All thrown exceptions | Enables diagnosis without debugging | +| **Empty over null** | Collections, strings, optionals | Eliminates NullPointerException risk | + +--- + +## Common Error Handling Anti-Patterns + +| Anti-pattern | Problem | Fix | +|-------------|---------|-----| +| **Catch-and-ignore** | `catch (Exception e) { }` -- swallows all errors silently | At minimum log; usually re-throw or handle specifically | +| **Catch-and-log-and-rethrow** | Duplicates logging at every level | Catch at one level, let others propagate | +| **Returning error codes** | Forces immediate checking, clutters happy path | Use exceptions | +| **Returning -1 or sentinel values** | Magic values that callers forget to check | Use Optional or throw | +| **Exception for control flow** | Using try-catch instead of if-else for expected conditions | Use exceptions only for exceptional situations | +| **Overly broad catch** | `catch (Exception e)` catches bugs too | Catch specific exception types | +| **Nested try-catch** | Multiple try blocks in one function | Extract each try block into its own function | +| **Throws declaration cascade** | Checked exceptions forcing changes up the call stack | Use unchecked exceptions for application errors | diff --git a/.agents/skills/clean-code/references/functions-and-methods.md b/.agents/skills/clean-code/references/functions-and-methods.md new file mode 100644 index 00000000..42aa7901 --- /dev/null +++ b/.agents/skills/clean-code/references/functions-and-methods.md @@ -0,0 +1,373 @@ +# Functions and Methods + +Comprehensive guide to writing small, focused functions that do one thing well. Based on Robert C. Martin's *Clean Code*, Chapters 3 and 4. + + +## Table of Contents +1. [The First Rule of Functions](#the-first-rule-of-functions) +2. [Do One Thing](#do-one-thing) +3. [Function Arguments](#function-arguments) +4. [Flag Arguments](#flag-arguments) +5. [Command-Query Separation](#command-query-separation) +6. [Side Effects](#side-effects) +7. [Extract Till You Drop](#extract-till-you-drop) +8. [Structured Programming](#structured-programming) +9. [DRY: Don't Repeat Yourself](#dry-dont-repeat-yourself) +10. [Function Organization Within a Class](#function-organization-within-a-class) +11. [Common Function Anti-Patterns](#common-function-anti-patterns) + +--- + +## The First Rule of Functions + +**Functions should be small.** The second rule of functions is that they should be smaller than that. + +A well-written function: +- Fits on one screen (ideally 4-10 lines) +- Has a name that describes exactly what it does +- Takes few arguments (zero is best, three is the maximum) +- Has no side effects +- Operates at a single level of abstraction + +--- + +## Do One Thing + +**Functions should do one thing. They should do it well. They should do it only.** + +### How to Know if a Function Does One Thing + +If you can extract another function from it with a name that is not merely a restatement of its implementation, the function does more than one thing. + +```python +# BAD: Does three things +def process_payment(order): + # 1. Validate + if not order.items: + raise ValueError("Empty order") + if order.total <= 0: + raise ValueError("Invalid total") + + # 2. Charge + payment_result = gateway.charge(order.customer.card, order.total) + if not payment_result.success: + raise PaymentError(payment_result.error) + + # 3. Notify + email_service.send_receipt(order.customer.email, order) + analytics.track("payment_completed", order.id) + +# GOOD: Does one thing, delegates details +def process_payment(order): + validate_order(order) + charge_customer(order) + send_notifications(order) +``` + +### The Step-Down Rule + +Code should read like a top-down narrative. Every function should be followed by the next level of abstraction. + +``` +To process a payment: + We validate the order. + We charge the customer. + We send notifications. + +To validate the order: + We check it has items. + We check the total is positive. + +To charge the customer: + We call the payment gateway. + We handle any payment failure. + +To send notifications: + We email the receipt. + We track the analytics event. +``` + +This reads like a newspaper: the headline (top-level function) tells you the story, and each successive paragraph (sub-function) provides more detail. + +--- + +## Function Arguments + +The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification. + +### Argument Count Guide + +| Count | Name | When acceptable | Example | +|-------|------|-----------------|---------| +| **0** | Niladic | Simple operations | `getCurrentTime()` | +| **1** | Monadic | Asking a question or transforming input | `isValid(email)`, `parse(json)` | +| **2** | Dyadic | Natural pairings | `Point(x, y)`, `assertEquals(expected, actual)` | +| **3** | Triadic | Rarely; consider object | `Color(r, g, b)` | +| **4+** | Polyadic | Almost never | Wrap in object: `new Config(...)` | + +### Common Monadic Forms + +Three common reasons to pass a single argument: + +1. **Asking a question:** `boolean fileExists(path)` -- returns true/false about the argument +2. **Transforming it:** `InputStream fileOpen(path)` -- transforms the argument and returns the result +3. **Event:** `void passwordAttemptFailedNTimes(attempts)` -- uses the argument to alter system state (make this clear from the name) + +### Why Many Arguments Are Problematic + +```java +// BAD: What does each argument mean? What order? +createReport(title, startDate, endDate, format, includeCharts, sendEmail, recipients); + +// GOOD: Parameter object groups related arguments +ReportConfig config = new ReportConfig.Builder() + .title("Q4 Revenue") + .dateRange(startDate, endDate) + .format(PDF) + .includeCharts(true) + .build(); +createReport(config); +``` + +Each argument increases the difficulty of understanding, testing, and calling the function. Arguments also create ordering dependencies that the reader must memorize. + +--- + +## Flag Arguments + +**Flag arguments are ugly.** Passing a boolean into a function loudly declares that the function does two things -- one thing if the flag is true, another if false. + +```python +# BAD: Flag argument +def render(document, is_for_print): + if is_for_print: + # 20 lines of print rendering + ... + else: + # 20 lines of screen rendering + ... + +# GOOD: Two clearly named functions +def render_for_print(document): + ... + +def render_for_screen(document): + ... +``` + +If a function must behave differently based on a condition, split it into two named functions. If the behaviors share logic, extract the shared part into a private helper. + +--- + +## Command-Query Separation + +Functions should either do something (command) or answer something (query), but not both. + +```java +// BAD: Does this set the attribute or check if it exists? +if (set("username", "unclebob")) { ... } + +// GOOD: Separate query from command +if (attributeExists("username")) { + setAttribute("username", "unclebob"); +} +``` + +**Commands** change the state of an object. They should return void. +**Queries** return information about an object. They should not change state. + +When a function both changes state and returns a value, the reader cannot tell from the call site what is happening. + +--- + +## Side Effects + +A side effect is when a function promises to do one thing but also does other hidden things. + +### Common Hidden Side Effects + +| Declared purpose | Hidden side effect | Danger | +|-----------------|-------------------|--------| +| `checkPassword(user, password)` | Initializes a session | Calling "check" unexpectedly logs user in | +| `getUser(id)` | Creates user if not found | "Get" implies read-only; caller doesn't expect writes | +| `toString()` | Modifies internal state | Debugging with print statements changes behavior | +| `validate(input)` | Sends analytics event | Validation during testing triggers real events | + +### How to Fix Side Effects + +1. **Make the side effect explicit in the name:** `checkPasswordAndInitSession()` +2. **Separate the concerns:** `checkPassword()` + `initSession()` as two calls +3. **Prefer option 2** -- separation makes testing easier and keeps functions honest + +--- + +## Extract Till You Drop + +If you can extract a named function from a block of code, you should. The extracted function's name adds documentation value, even if the function is only called from one place. + +### When to Extract + +| Signal | Action | +|--------|--------| +| A block inside an `if`, `else`, `for`, or `while` | Extract to named function | +| A comment explaining what the next lines do | Replace comment with named function | +| A function longer than 10 lines | Look for extraction opportunities | +| Nested indentation deeper than 2 levels | Extract inner blocks | +| Code that you'd need to re-read to understand | Name it so you don't have to | + +### Extraction Example + +```typescript +// BEFORE: Deeply nested, hard to follow +function processOrders(orders: Order[]) { + for (const order of orders) { + if (order.status === 'pending') { + let total = 0; + for (const item of order.items) { + if (item.inStock) { + total += item.price * item.quantity; + if (item.quantity > 10) { + total *= 0.9; // bulk discount + } + } + } + if (total > 0) { + order.total = total; + order.status = 'processed'; + db.save(order); + emailService.sendConfirmation(order); + } + } + } +} + +// AFTER: Each function does one thing +function processOrders(orders: Order[]) { + orders + .filter(isPending) + .forEach(processOrder); +} + +function processOrder(order: Order) { + const total = calculateOrderTotal(order); + if (total > 0) { + finalizeOrder(order, total); + } +} + +function calculateOrderTotal(order: Order): number { + return order.items + .filter(item => item.inStock) + .reduce((sum, item) => sum + calculateItemPrice(item), 0); +} + +function calculateItemPrice(item: Item): number { + const basePrice = item.price * item.quantity; + return item.quantity > BULK_DISCOUNT_THRESHOLD + ? basePrice * BULK_DISCOUNT_RATE + : basePrice; +} + +function finalizeOrder(order: Order, total: number) { + order.total = total; + order.status = 'processed'; + db.save(order); + emailService.sendConfirmation(order); +} +``` + +--- + +## Structured Programming + +Dijkstra's rule states that every function should have one entry and one exit: one `return` statement, no `break` or `continue` in loops, and never `goto`. + +**In practice, for small functions, multiple returns and early exits improve clarity:** + +```python +# Guard clauses improve readability in small functions +def calculate_discount(customer): + if customer is None: + return 0 + if not customer.is_active: + return 0 + if customer.total_purchases < MINIMUM_FOR_DISCOUNT: + return 0 + + return customer.total_purchases * DISCOUNT_RATE +``` + +Guard clauses handle the error cases at the top of the function, leaving the happy path unindented and clear. This pattern is preferable to deeply nested `if-else` chains. + +--- + +## DRY: Don't Repeat Yourself + +Duplication is the root of all evil in software. Every piece of knowledge should have a single, unambiguous, authoritative representation in the system. + +### Types of Duplication + +| Type | Example | Fix | +|------|---------|-----| +| **Exact duplication** | Same code block in three places | Extract to shared function | +| **Structural duplication** | Same algorithm with different data | Template Method or Strategy pattern | +| **Conceptual duplication** | Same business rule expressed differently | Consolidate into single source of truth | +| **Data duplication** | Same value computed in multiple places | Compute once, pass result | + +### The Rule of Three + +The first time you write something, just write it. The second time you see duplication, note it. The third time, refactor. This avoids premature abstraction while still catching genuine duplication. + +--- + +## Function Organization Within a Class + +### The Newspaper Metaphor + +Organize functions the way a newspaper organizes articles: + +1. **Headline at the top:** Public methods (the API) appear first +2. **Synopsis next:** High-level private methods called by the public methods +3. **Details last:** Low-level helper functions at the bottom + +The reader can stop reading at any depth once they have enough understanding. + +### Vertical Distance + +**Dependent functions should be close.** If one function calls another, they should be vertically close in the source file, and the caller should be above the callee. + +```java +// GOOD: Caller above callee, close together +public void processOrder(Order order) { + validateOrder(order); + chargeCustomer(order); + shipOrder(order); +} + +private void validateOrder(Order order) { + // validation logic +} + +private void chargeCustomer(Order order) { + // payment logic +} + +private void shipOrder(Order order) { + // shipping logic +} +``` + +**Variables should be declared as close to their usage as possible.** Local variables at the top of the function. Loop variables inside the loop statement. Instance variables at the top of the class (everyone needs to know they exist). + +--- + +## Common Function Anti-Patterns + +| Anti-pattern | Problem | Refactoring | +|-------------|---------|-------------| +| **Output arguments** | `appendFooter(report)` -- is `report` input or output? | Make it a method: `report.appendFooter()` | +| **Selector arguments** | `calculate(MONTHLY)` enum switches behavior | Split: `calculateMonthly()`, `calculateAnnual()` | +| **Dead functions** | Never called, just sitting there | Delete them. Version control remembers. | +| **Switch statements** | Long switches violate SRP and OCP | Replace with polymorphism or strategy pattern | +| **Temporal coupling** | Functions must be called in a specific order | Make ordering explicit through return values or builder | +| **Leaky abstraction** | Function exposes implementation details | Hide internals, return domain objects | diff --git a/.agents/skills/clean-code/references/naming-conventions.md b/.agents/skills/clean-code/references/naming-conventions.md new file mode 100644 index 00000000..c20e72d3 --- /dev/null +++ b/.agents/skills/clean-code/references/naming-conventions.md @@ -0,0 +1,280 @@ +# Naming Conventions + +Comprehensive guide to choosing names that reveal intent, avoid disinformation, and make code read like well-written prose. Based on Robert C. Martin's *Clean Code*, Chapter 2. + +## The Golden Rule + +**A name should tell you why it exists, what it does, and how it is used.** If a name requires a comment to explain it, the name does not reveal its intent. + +--- + +## Intention-Revealing Names + +The name of a variable, function, or class should answer three questions: +1. Why does it exist? +2. What does it do? +3. How is it used? + +### Before and After + +| Before | After | Why it's better | +|--------|-------|-----------------| +| `d` | `elapsedTimeInDays` | Reveals what the number represents | +| `list` | `flaggedAccounts` | Describes *which* list and *why* it exists | +| `hp` | `isHighPriority` | Self-documents its boolean nature and meaning | +| `temp` | `unprocessedBatchItems` | Communicates purpose, not temporary status | +| `x`, `y` | `latitude`, `longitude` | Domain language replaces abstract math symbols | +| `val` | `discountPercentage` | Specifies what value and its unit | +| `data` | `customerOrderHistory` | Names the specific data, not the generic concept | +| `info` | `shippingTrackingDetails` | Adds specificity to a meaningless suffix | + +### Code Example + +```python +# BAD: What does this do? +def get_them(the_list): + result = [] + for x in the_list: + if x[0] == 4: + result.append(x) + return result + +# GOOD: Intention is revealed +def get_flagged_cells(game_board): + flagged_cells = [] + for cell in game_board: + if cell.is_flagged(): + flagged_cells.append(cell) + return flagged_cells +``` + +--- + +## Avoiding Disinformation + +Disinformation means using names that imply something different from the actual meaning. + +**Rules:** +- Don't use `accountList` unless it is actually a `List` type -- use `accounts` or `accountGroup` +- Don't use names that vary in small ways: `XYZControllerForEfficientHandlingOfStrings` vs `XYZControllerForEfficientStorageOfStrings` +- Don't use lowercase `L` or uppercase `O` as variable names (look like `1` and `0`) +- Don't use names of other well-known entities: `hp`, `aix`, `sco` are Unix platform names + +### Common Disinformation Patterns + +| Disinformation | Problem | Fix | +|----------------|---------|-----| +| `accountList` when it's a `Set` | Implies ordered, duplicates allowed | Use `accounts` | +| `name1`, `name2` | Implies ordering or relationship that doesn't exist | Use meaningful distinction: `firstName`, `lastName` | +| `strName` | Hungarian notation; type may change | Just use `name` | +| `theAccount` vs `account` | No meaningful distinction | Pick one, use it consistently | + +--- + +## Meaningful Distinctions + +If names must be different, they should mean something different. + +**Noise words are meaningless distinctions:** +- `Product` vs `ProductInfo` vs `ProductData` -- what's the difference? +- `getAccount()` vs `getAccountInfo()` vs `getAccountData()` -- indistinguishable +- `name` vs `nameString` -- is `name` a floating-point number? + +**The test:** If you cannot tell what two similarly named things do without reading their implementations, the names fail. + +### How to Make Meaningful Distinctions + +| Instead of | Use | Rationale | +|------------|-----|-----------| +| `copyChars(a1, a2)` | `copyChars(source, destination)` | Arguments reveal their role | +| `moneyAmount` vs `money` | Just `money` | Amount is implied by the context | +| `theMessage` vs `message` | Just `message` | The article adds no information | +| `accountData` vs `account` | Just `account` | Data is inherent -- what else would it be? | + +--- + +## Pronounceable Names + +If you cannot pronounce a name, you cannot discuss it without sounding foolish. + +| Unpronounceable | Pronounceable | +|-----------------|---------------| +| `genymdhms` | `generationTimestamp` | +| `modymdhms` | `modificationTimestamp` | +| `pszqint` | `formattedQuantity` | +| `cstmrAddr` | `customerAddress` | + +**Why it matters:** Programming is a social activity. You discuss code in reviews, pairing, design meetings, and stand-ups. Names you cannot say out loud create communication barriers. + +--- + +## Searchable Names + +Single-letter names and numeric constants are impossible to search for in a large codebase. + +**Rule of thumb:** The length of a name should correspond to the size of its scope. + +| Scope | Name length | Example | +|-------|-------------|---------| +| Single-line lambda | 1 character acceptable | `items.map(x => x.id)` | +| Loop body (3-5 lines) | 1-2 characters acceptable | `for i in range(len(items))` | +| Method scope | Descriptive word(s) | `retryCount`, `matchingUser` | +| Class scope | Fully descriptive phrase | `maximumQueueCapacity` | +| Module/global scope | Complete, searchable phrase | `DEFAULT_CONNECTION_TIMEOUT_MS` | + +### Constants Must Be Named + +```javascript +// BAD: What does 5 mean? What does 7 mean? +if (retries > 5) { ... } +setTimeout(fn, 7 * 86400000); + +// GOOD: Self-documenting +const MAX_RETRY_ATTEMPTS = 5; +const CACHE_EXPIRY_DAYS = 7; +const MS_PER_DAY = 86400000; + +if (retries > MAX_RETRY_ATTEMPTS) { ... } +setTimeout(fn, CACHE_EXPIRY_DAYS * MS_PER_DAY); +``` + +--- + +## Class Names vs. Method Names + +### Class Names: Nouns and Noun Phrases + +Classes represent things. Their names should be nouns or noun phrases. + +| Good | Bad | Why | +|------|-----|-----| +| `Customer` | `CustomerManager` | Manager is vague -- what does it manage? | +| `WikiPage` | `WebPage` | More specific to the domain | +| `AddressParser` | `ParseAddress` | Noun phrase, not a verb | +| `InvoiceRepository` | `InvoiceProcessor` | Processor is vague -- what processing? | +| `Account` | `AccountData` | Data suffix is noise | + +**Avoid:** `Manager`, `Processor`, `Data`, `Info` -- these are weasel words that indicate the class has no clear responsibility. + +### Method Names: Verbs and Verb Phrases + +Methods represent actions. Their names should be verbs or verb phrases. + +| Good | Bad | Why | +|------|-----|-----| +| `save()` | `doSave()` | `do` prefix is noise | +| `calculateTax()` | `tax()` | Verb clarifies it computes, not stores | +| `isValid()` | `checkValid()` | Boolean accessor follows `is`/`has`/`can` convention | +| `fromJson(str)` | `parse(str)` | Static factory name describes transformation | +| `deleteExpiredSessions()` | `cleanup()` | Specific about what gets cleaned | + +### Accessor, Mutator, and Predicate Conventions + +```java +// Accessors: get + property +String getName() +int getAge() + +// Mutators: set + property +void setName(String name) +void setAge(int age) + +// Predicates: is/has/can + condition +boolean isEmpty() +boolean hasPermission(Role role) +boolean canExecute() +``` + +--- + +## Naming Conventions by Language + +### Python +- `snake_case` for functions and variables: `calculate_total`, `user_count` +- `PascalCase` for classes: `UserAccount`, `OrderProcessor` +- `UPPER_SNAKE_CASE` for constants: `MAX_RETRIES`, `DEFAULT_TIMEOUT` +- `_leading_underscore` for private: `_internal_cache` +- `__dunder__` for magic methods: `__init__`, `__str__` + +### JavaScript/TypeScript +- `camelCase` for functions and variables: `calculateTotal`, `userCount` +- `PascalCase` for classes and components: `UserAccount`, `OrderList` +- `UPPER_SNAKE_CASE` for constants: `MAX_RETRIES`, `API_BASE_URL` +- `#privateField` for private class fields (ES2022+) + +### Java +- `camelCase` for methods and variables: `calculateTotal()`, `userCount` +- `PascalCase` for classes: `UserAccount`, `OrderService` +- `UPPER_SNAKE_CASE` for constants: `MAX_RETRIES` +- Packages: `com.company.project.module` + +### Go +- `PascalCase` for exported (public): `CalculateTotal`, `UserCount` +- `camelCase` for unexported (private): `calculateTotal`, `userCount` +- Short names acceptable for small scopes: `r` for reader, `w` for writer +- Acronyms stay uppercase: `HTTPClient`, `XMLParser`, `userID` + +### Rust +- `snake_case` for functions and variables: `calculate_total`, `user_count` +- `PascalCase` for types and traits: `UserAccount`, `Serialize` +- `UPPER_SNAKE_CASE` for constants and statics: `MAX_RETRIES` +- Lifetime names: short lowercase `'a`, `'b` or descriptive `'input`, `'output` + +--- + +## The Pick-One-Word-Per-Concept Rule + +Using different words for the same abstract concept is confusing. + +| Inconsistent | Consistent | Rule | +|-------------|------------|------| +| `fetch` / `retrieve` / `get` | Pick `get` everywhere | One word for the read operation | +| `controller` / `manager` / `driver` | Pick `controller` everywhere | One word for the coordination role | +| `create` / `make` / `build` / `new` | Pick `create` for API, `build` for complex assembly | Differentiate only if semantics differ | +| `remove` / `delete` / `destroy` | `delete` for permanent, `remove` for detach | Different words when semantics differ | + +--- + +## Solution Domain vs. Problem Domain Names + +**Use solution domain names** when the concept is a well-known computer science term: +- `Queue`, `Stack`, `HashMap`, `Factory`, `Visitor`, `Iterator` +- Fellow programmers will recognize these instantly + +**Use problem domain names** when the concept belongs to the business: +- `Invoice`, `Shipment`, `PolicyHolder`, `ClaimAdjuster` +- Domain experts and future maintainers will understand these + +**The priority:** Problem domain names first, solution domain names second. Code that reads in business terms is easier for the whole team -- developers, testers, product managers -- to discuss and verify. + +--- + +## Common Anti-Patterns + +### Names to Avoid + +| Anti-pattern | Example | Problem | +|-------------|---------|---------| +| **Single letter** | `a`, `b`, `t` | Meaningless outside tiny loops | +| **Abbreviation** | `acct`, `mgr`, `btn`, `usr` | Saves milliseconds, costs hours | +| **Generic suffix** | `DataObject`, `InfoManager` | Adds nothing; signals unclear responsibility | +| **Type encoding** | `sName`, `iCount`, `bFlag` | IDE shows types; encoding is obsolete and misleading | +| **Numbered series** | `arg1`, `arg2`, `arg3` | Provides no information about each argument's role | +| **Mental mapping** | `r` means URL (in the author's head) | Forces readers to maintain a mental translation table | +| **Puns** | `add` meaning both "concatenate" and "insert" | Same word, different semantics creates confusion | + +--- + +## Renaming Checklist + +When renaming a variable, function, or class, follow this checklist to ensure the change improves clarity: + +1. **Does the new name reveal intent?** The reader should understand purpose without reading the implementation. +2. **Is it pronounceable?** Can you say it in a code review without spelling it out? +3. **Is it searchable?** Can you find all occurrences with a simple text search? +4. **Does it avoid disinformation?** The name should not imply something the code does not do. +5. **Is it consistent with the codebase?** Use the same word for the same concept everywhere. +6. **Is the length proportional to scope?** Short names for tiny scopes, long names for large scopes. +7. **Does it use domain language?** Prefer business terminology over generic programming terms. + +**Remember:** Renaming is one of the most powerful refactorings. Modern IDEs make it safe and fast. Never hesitate to rename something that is unclear -- your future self and your teammates will thank you. diff --git a/.agents/skills/clean-code/references/testing-principles.md b/.agents/skills/clean-code/references/testing-principles.md new file mode 100644 index 00000000..f0c27b46 --- /dev/null +++ b/.agents/skills/clean-code/references/testing-principles.md @@ -0,0 +1,353 @@ +# Testing Principles + +Comprehensive guide to writing clean, maintainable tests that serve as executable documentation. Based on Robert C. Martin's *Clean Code*, Chapter 9. + + +## Table of Contents +1. [Why Tests Matter](#why-tests-matter) +2. [The Three Laws of TDD](#the-three-laws-of-tdd) +3. [Clean Tests](#clean-tests) +4. [One Concept Per Test](#one-concept-per-test) +5. [F.I.R.S.T. Principles](#first-principles) +6. [Test Naming](#test-naming) +7. [Test Patterns and Practices](#test-patterns-and-practices) +8. [Tests as Documentation](#tests-as-documentation) + +--- + +## Why Tests Matter + +Test code is just as important as production code. It is not a second-class citizen. It requires thought, design, and care. Dirty tests are equivalent to, if not worse than, having no tests. Tests that are hard to read, fragile, or slow become a liability that developers avoid and eventually delete. + +**The fundamental equation:** Clean tests = confidence to refactor = clean production code. Without tests, every change is a potential bug. With dirty tests, every change requires fighting through incomprehensible test code. With clean tests, refactoring is fearless. + +--- + +## The Three Laws of TDD + +Test-Driven Development follows three simple rules: + +| Law | Rule | What it means | +|-----|------|---------------| +| **First** | You may not write production code until you have written a failing unit test | Tests drive the design, not the other way around | +| **Second** | You may not write more of a unit test than is sufficient to fail (compilation failures count) | Write the minimum test that fails | +| **Third** | You may not write more production code than is sufficient to pass the currently failing test | Write the minimum code that passes | + +### The Red-Green-Refactor Cycle + +1. **Red:** Write a failing test (it should fail for the right reason) +2. **Green:** Write the simplest code that makes the test pass (even if ugly) +3. **Refactor:** Clean up both production code and test code while keeping all tests green + +This cycle runs in seconds to minutes, not hours. Each cycle produces one small, tested increment. + +### Benefits of TDD + +| Benefit | Why | +|---------|-----| +| **Nearly 100% coverage** | Every line of production code was written to pass a test | +| **Tests as documentation** | Tests show exactly how the code is intended to be used | +| **Fearless refactoring** | You know immediately if a change breaks something | +| **Better design** | Hard-to-test code is hard to use; TDD pushes toward clean design | +| **Debugging reduction** | When a test fails, the bug is in the last few lines you wrote | + +--- + +## Clean Tests + +### What Makes a Test Clean? + +**Readability.** The same thing that makes production code clean makes test code clean: readability. What makes tests readable? The same thing that makes all code readable: clarity, simplicity, and density of expression. In a test, you want to say a lot with as few expressions as possible. + +### The Build-Operate-Check Pattern + +Every clean test has three distinct phases: + +```python +def test_should_apply_bulk_discount_when_quantity_exceeds_threshold(): + # BUILD: Create the test data + order = an_order() + .with_item(product="Widget", quantity=25, unit_price=10.00) + .build() + + # OPERATE: Execute the behavior under test + invoice = billing_service.generate_invoice(order) + + # CHECK: Verify the expected outcome + assert invoice.total == 225.00 # 250 - 10% bulk discount + assert invoice.discount_applied == "BULK_10" +``` + +Also known as **Arrange-Act-Assert** or **Given-When-Then**. + +### Domain-Specific Testing Language + +Build utility functions and helpers that read like a domain-specific language for your tests. + +```python +# BAD: Raw setup code obscures the test's intent +def test_expired_subscription(): + user = User( + id=uuid4(), + name="Alice", + email="alice@example.com", + created_at=datetime(2024, 1, 1), + subscription=Subscription( + plan="pro", + status="active", + expires_at=datetime(2024, 1, 15), + ), + ) + user.subscription.check_expiry(current_date=datetime(2024, 2, 1)) + assert user.subscription.status == "expired" + +# GOOD: Helpers create a readable narrative +def test_expired_subscription(): + user = a_user().with_pro_subscription(expires_on="2024-01-15").build() + + user.check_subscription_on("2024-02-01") + + assert_that(user).has_expired_subscription() +``` + +The test reads like a specification: "Given a user with a pro subscription expiring on Jan 15, when we check the subscription on Feb 1, then the subscription should be expired." + +--- + +## One Concept Per Test + +Each test function should test one concept. This does not necessarily mean one assert per test -- it means one logical assertion, one behavioral expectation. + +### One Concept, Multiple Asserts (Acceptable) + +```python +def test_should_create_valid_invoice_from_order(): + order = an_order().with_two_items().build() + + invoice = billing_service.generate_invoice(order) + + assert invoice.customer == order.customer + assert invoice.line_items_count == 2 + assert invoice.total == order.calculated_total + assert invoice.status == "pending" +``` + +All four asserts verify one concept: "generating an invoice from an order produces a valid invoice." + +### Multiple Concepts (Split Into Separate Tests) + +```python +# BAD: Two concepts in one test +def test_invoice_generation(): + order = an_order().build() + invoice = billing_service.generate_invoice(order) + assert invoice.total == order.calculated_total # Concept 1: correct total + + invoice.mark_as_paid() + assert invoice.status == "paid" # Concept 2: payment status transition + +# GOOD: Each test covers one concept +def test_should_calculate_correct_invoice_total(): + order = an_order().with_total(150.00).build() + invoice = billing_service.generate_invoice(order) + assert invoice.total == 150.00 + +def test_should_transition_to_paid_when_marked_as_paid(): + invoice = an_invoice().with_status("pending").build() + invoice.mark_as_paid() + assert invoice.status == "paid" +``` + +--- + +## F.I.R.S.T. Principles + +Clean tests follow five principles that form the acronym F.I.R.S.T.: + +### Fast + +Tests should be fast. When tests run slowly, you won't run them frequently. When you don't run them frequently, you won't find problems early. When you don't find problems early, you won't fix them easily. + +| Guideline | Target | How | +|-----------|--------|-----| +| Unit test suite | Under 10 seconds | Mock all external dependencies | +| Individual test | Under 100ms | No I/O, no network, no database | +| Integration tests | Separate suite | Run separately, not on every save | + +### Independent + +Tests should not depend on each other. One test should not set up conditions for the next. You should be able to run each test independently and in any order. + +```python +# BAD: Test B depends on Test A's side effects +def test_a_create_user(): + global test_user + test_user = UserService.create("Alice") + +def test_b_update_user(): + UserService.update(test_user.id, name="Bob") # Fails if A doesn't run first + +# GOOD: Each test is self-contained +def test_create_user(): + user = UserService.create("Alice") + assert user.name == "Alice" + +def test_update_user(): + user = UserService.create("Alice") # Own setup + updated = UserService.update(user.id, name="Bob") + assert updated.name == "Bob" +``` + +### Repeatable + +Tests should produce the same result every time, in any environment -- development machine, CI server, production-like staging. Tests that depend on network availability, current time, or random data are flaky. + +| Flaky dependency | Fix | +|-----------------|-----| +| Current time | Inject a clock; mock `datetime.now()` | +| Random data | Use seeded random or fixed test data | +| Network calls | Mock HTTP clients | +| Database state | Use transactions that roll back, or in-memory DB | +| File system | Use temp directories; clean up in teardown | +| Environment variables | Set explicitly in test setup | + +### Self-Validating + +Tests should have a boolean output: pass or fail. No manual interpretation required. + +```python +# BAD: Requires human to check output +def test_report_generation(): + report = generate_report() + print(report) # Developer must read and visually verify + +# GOOD: Automated assertion +def test_report_generation(): + report = generate_report() + assert report.title == "Q4 Revenue Report" + assert report.total_revenue == 142_500.00 + assert len(report.line_items) == 12 +``` + +### Timely + +Tests should be written just before the production code that makes them pass (TDD). Tests written after the fact are harder to write because the production code may not be designed for testability. You may decide that some production code is "too hard to test" -- which really means it's too coupled. + +--- + +## Test Naming + +Test names should describe the scenario being tested and the expected behavior. + +### Naming Patterns + +| Pattern | Example | When to use | +|---------|---------|-------------| +| `should_[expected]_when_[condition]` | `should_reject_login_when_password_expired` | Most common; clear cause-effect | +| `[method]_[scenario]_[expected]` | `withdraw_insufficient_funds_throws_exception` | When testing a specific method | +| `given_[state]_when_[action]_then_[result]` | `given_empty_cart_when_checkout_then_error` | BDD-style | +| `test_[behavior_description]` | `test_expired_tokens_are_rejected` | Simple, readable | + +### Bad Test Names + +| Bad name | Problem | Better name | +|----------|---------|-------------| +| `test1` | Meaningless | `test_empty_input_returns_empty_list` | +| `testProcess` | What about process? | `test_process_skips_inactive_users` | +| `testCalculate` | Too vague | `test_calculate_applies_weekend_surcharge` | +| `testBug1234` | Won't make sense in 6 months | `test_duplicate_orders_are_rejected` | + +--- + +## Test Patterns and Practices + +### Parameterized Tests + +When testing the same behavior with different inputs, use parameterized tests instead of copy-pasting. + +```python +@pytest.mark.parametrize("input_email,expected_valid", [ + ("user@example.com", True), + ("user@sub.example.com", True), + ("user@example", False), + ("@example.com", False), + ("user@.com", False), + ("", False), +]) +def test_email_validation(input_email, expected_valid): + assert validate_email(input_email) == expected_valid +``` + +### Test Fixtures and Builders + +Use the Builder pattern for test data to make tests readable and maintainable. + +```python +class UserBuilder: + def __init__(self): + self._name = "Default User" + self._email = "default@example.com" + self._role = "viewer" + self._active = True + + def with_name(self, name): self._name = name; return self + def with_role(self, role): self._role = role; return self + def inactive(self): self._active = False; return self + def build(self): + return User( + name=self._name, email=self._email, + role=self._role, active=self._active, + ) + +def a_user(): + return UserBuilder() + +# Usage in tests +admin = a_user().with_name("Alice").with_role("admin").build() +inactive_user = a_user().inactive().build() +``` + +### Testing Error Paths + +Every error path in production code should have a corresponding test. + +```python +def test_should_raise_on_negative_amount(): + account = an_account().with_balance(100).build() + with pytest.raises(ValueError, match="Amount must be positive"): + account.withdraw(-50) + +def test_should_raise_on_insufficient_funds(): + account = an_account().with_balance(100).build() + with pytest.raises(InsufficientFundsError): + account.withdraw(150) +``` + +### Boundary Condition Tests + +Test the edges, not just the middle. + +| Boundary | Tests needed | +|----------|-------------| +| Empty input | `[]`, `""`, `None`, `{}` | +| Single element | List with one item, string with one char | +| Maximum values | `MAX_INT`, full capacity, max length | +| Off-by-one | `n-1`, `n`, `n+1` for any threshold | +| Transition points | Just below and just above limits | +| Overflow/underflow | Values that exceed type boundaries | + +--- + +## Tests as Documentation + +Clean tests serve as the most reliable documentation of how the system behaves. Unlike comments or wiki pages, tests are always up to date -- if they weren't, they'd be failing. + +| Documentation type | Tests provide | +|-------------------|---------------| +| **API usage** | Test setup shows how to call the API | +| **Expected behavior** | Assertions describe what should happen | +| **Edge cases** | Boundary tests document special cases | +| **Error behavior** | Error path tests document failure modes | +| **Business rules** | Test names describe domain rules | + +When a new developer asks "how does this work?", point them to the tests. Clean tests answer the question better than any comment or README. diff --git a/.agents/skills/cold-start-problem/SKILL.md b/.agents/skills/cold-start-problem/SKILL.md new file mode 100644 index 00000000..ac44a85c --- /dev/null +++ b/.agents/skills/cold-start-problem/SKILL.md @@ -0,0 +1,188 @@ +--- +name: cold-start-problem +description: 'Start and scale networked products using Andrew Chen''s "The Cold Start Problem" framework for network effects. Use when the user mentions "network effects", "chicken and egg", "cold start", "two-sided marketplace", "atomic network", "hard side", "liquidity", "critical mass", "invite-only launch", "how do I get my first users", or "the marketplace has no buyers or sellers". Also trigger when launching a marketplace, social, or collaboration product that is worthless without other users, deciding launch sequencing and seeding tactics, or diagnosing stalled network growth at scale. Covers the five stages: cold start, tipping point, escape velocity, hitting the ceiling, and the moat. For word-of-mouth virality, see contagious. For habit-driven retention, see hooked-ux.' +license: MIT +metadata: + author: wondelai + version: "1.2.0" +--- + +# The Cold Start Problem + +A framework for starting and scaling products that live or die by network effects — marketplaces, social apps, messaging, and collaboration tools — distilled from Andrew Chen's *The Cold Start Problem*. Use it to launch products that are worthless until other users show up, to sequence growth network by network, and to navigate the five stages: the cold start, the tipping point, escape velocity, hitting the ceiling, and the moat. + +## Core Principle + +**Network effects start as a liability, not an asset.** Value lives in connections between users, and on day one there are none — the same force that makes a dense network unstoppable makes an empty one useless. You don't escape by launching to a market; you escape by building one tiny, complete, self-sustaining network at a time, solving its hard side first, then tipping adjacent networks with a repeatable playbook until the market follows. + +## Scoring + +**Goal: 10/10.** Rate launch plans and growth strategies for networked products 0-10 against the principles below. Report the current score and the specific changes needed to reach 10/10. + +- **9-10:** Named atomic network with an instrumented magic moment, hard side solved first, repeatable tipping playbook, density/liquidity metrics, explicit ceiling and moat plan +- **7-8:** Clear atomic network and hard-side focus, but tipping tactics are ad hoc or metrics still track totals over density +- **5-6:** Network effects acknowledged, but the launch targets a broad market and both sides are treated equally +- **3-4:** Generic user-acquisition plan; network thinking limited to "add invites and hope it spreads" +- **0-2:** Big-bang launch to everyone at once, vanity signups, no hard-side strategy, no liquidity measures + +## Framework + +### 1. Network Effects Fundamentals + +**Core concept:** A networked product connects people with each other — buyers with sellers, creators with audiences, coworkers with coworkers — and becomes more valuable as the right people join. Network effects come in three distinct forms: the acquisition effect (the network pulls in its own new users), the engagement effect (more users make each session more valuable), and the economic effect (density improves monetization and unit economics). A product can be strong in one and weak in the others. + +**Why it works:** Treating "network effects" as a single magic property hides where growth actually comes from and where it breaks. Metcalfe's law (value grows with n²) is an oversimplification — it counts nodes, not active, relevant connections, and a million scattered users can be worth less than five thousand in one dense community. Every large network is really a network of networks: Uber is hundreds of city-level markets, Slack is millions of team-sized networks. Density and quality of each sub-network beat raw user counts. + +**Key insights:** +- The three effects decouple: viral acquisition can mask dead engagement — downloads up, rooms empty +- Metcalfe counts nodes; value lives in active connections — measure density, not totals +- Anti-network effects are real: the dynamics that compound growth in a dense network compound emptiness in a sparse one +- The network, not the feature set, is the moat — competitors can copy the product but not the people on it +- Aggregate metrics lie; cut every metric by sub-network (city, team, category) to see true health + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Metric design | Replace totals with density measures | Track weekly active networks, not registered users | +| Growth diagnosis | Attribute growth to the three effects separately | Viral factor vs. session frequency vs. conversion, each per network | +| Strategy review | Map the product as a network of networks | A marketplace is one network per city-category pair | + +See [references/case-studies.md](references/case-studies.md) for three end-to-end worked scenarios — a B2B tool finding its atomic network, a services marketplace seeding one city, a social app recovering from a big-bang launch — when you want a full example to model a plan on. + +### 2. The Cold Start: Atomic Networks + +**Core concept:** An atomic network is the smallest network that is stable and self-sustaining — just enough of the right people that the product delivers its core value and the group keeps returning on its own. Slack needs roughly three users inside one team, Zoom needs two, a marketplace may need a single zip code or category. Pick a network, not a market, and build the killer product for that tiny group — even when it looks unscalably niche. + +**Why it works:** Networks succeed or fail one network at a time. A product that works completely for fifty people in one community proves the loop and can be replicated; one that half-works for fifty thousand scattered users proves nothing and dies of emptiness. Tiny complete networks also expose the magic moment — the experience that shows the network working (the car arrives, the teammate replies) — which becomes the activation bar for every network that follows. + +**Key insights:** +- Smaller is better: find the minimum size at which the product works, then over-deliver for exactly that group +- Constrain the first network hard — one company, one campus, one neighborhood, one collector niche — so density is achievable with founder-level effort +- Define the magic moment precisely and instrument it; gate all expansion on networks reaching it +- Killer products for tiny networks look like toys (Facebook at Harvard, eBay's collectibles) — niche optics are the cost of density +- Flintstone the empty side: founders manually supply content, inventory, or matchmaking until the network stands alone + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Launch scoping | Pick a network, not a market | "Agents in one Austin brokerage," not "the US housing market" | +| Activation | Define and instrument the magic moment | New member posts and gets a teammate reply within minutes | +| Empty side | Flintstone missing supply manually | Founders personally fulfill the first 100 marketplace orders | + +**Ethical boundary:** Flintstoning means doing real work manually behind the scenes — never fabricating fake users, reviews, or activity that deceives the people on the network. + +See [references/atomic-networks.md](references/atomic-networks.md) when scoping the first launch — it has the 5-step minimum-size derivation, the actor/action/response/time magic-moment template, instrumentation and zero-rate steps, honest-flintstoning rules, single-player fallbacks, and a launch checklist. + +### 3. Solve the Hard Side + +**Core concept:** Every network has a hard side — a small minority who do disproportionate work and are disproportionately hard to attract and keep: sellers, creators, drivers, hosts, organizers. They have better alternatives and higher expectations, and without them the easy side finds an empty product. Understand their motivations — money, status, utility — and build the product and economics for them first. + +**Why it works:** The easy side shows up when the hard side delivers value, not before. A content app without creators, a marketplace without supply, a collaboration tool without the organizer who sets it up — all are empty rooms. "Come for the tool, stay for the network" is the classic hard-side wedge: a single-player tool (Instagram's filters, OpenTable's reservation book) recruits the hard side one by one before any network exists, and then the network makes leaving unthinkable. + +**Key insights:** +- Identify the hard side by work done, not money paid: a few percent of users create most of the value on Wikipedia, YouTube, and most marketplaces +- Map motivations explicitly: money (drivers, sellers), status (creators, top reviewers), utility (organizers who need the tool anyway) — each demands different product investments +- Build pro workflows and economics for the hard side first; the easy side mostly needs a clean consumer experience +- Subsidize the scarce side early — guarantees, bonuses, zero fees — and publish the taper so trust survives the rollback +- Early hard-siders professionalize fast: plan power tools, analytics, and payout improvements for month three, not year three + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Marketplace seeding | Recruit and subsidize supply before demand | Guarantee cleaner earnings for eight weeks pre-launch | +| Social or content app | Court creators with status and reach | Early-follower advantage, featuring, creator funds | +| B2B collaboration | Give the organizer single-player value | Project tracker useful alone; inviting the team makes it better | + +**Ethical boundary:** Hard-side economics must be honest — present launch subsidies as temporary incentives, and never build people's livelihoods on terms you plan to quietly degrade. + +See [references/hard-side.md](references/hard-side.md) when designing supply-side acquisition and economics — it maps money/status/utility motivations to product investments and details three named playbooks (tools-first, content-first, subsidies). + +### 4. Tipping Point and Escape Velocity + +**Core concept:** Once the first atomic network works, growth becomes a repeatable playbook for tipping the next network, and the next — each launch cheaper than the last. The core tipping tools: invite-only mechanics (curation + scarcity + social proof), paying up for launch (subsidies, guarantees, pre-committed supply), and influencer or community seeding. After tipping, escape velocity is not a milestone but an operating model: continuously amplifying the acquisition, engagement, and economic effects. + +**Why it works:** Invite-only launches look exclusionary but build density by design — every invitee arrives with at least one connection already inside, the network copies in along real social graphs, and scarcity manufactures the social proof that pulls the next cohort. Paying up converts money into density, the one asset rivals can't copy. Big-bang launches do the opposite: Google+ pushed hundreds of millions of signups into empty rooms, and the weak networks never retained. + +**Key insights:** +- Invite-only does three jobs at once: curates early culture, creates scarcity buzz, and imports each user's social graph +- Subsidies are network CAC: spend to manufacture liquidity, measure cost per active network, taper on a published schedule +- Big-bang launch is the canonical anti-pattern — fast fill, weak networks; press spikes land on emptiness and never return +- After tipping, run the three forces as named workstreams: acquisition (viral loops, referrals), engagement (reinforcing loops, re-engagement), economic (conversion, subsidy rollback, pricing) +- Each tipped network lowers the cost of the next: spillover awareness, a portable playbook, reusable supply relationships + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Consumer launch | Invite-only with a referral tree | Waitlist plus five invites per active user; track invite-graph density | +| Marketplace city #2 | Pay up to manufacture liquidity | Ninety-day driver earnings guarantee, tapered as fill rate rises | +| Post-tip growth | Staff the three forces as workstreams | Referral loop, digest re-engagement, take-rate optimization | + +**Ethical boundary:** Scarcity and exclusivity must be real — fake waitlists and manufactured "limited spots" are deception, not strategy. + +See [references/tipping-playbooks.md](references/tipping-playbooks.md) when planning network #2 onward — invite-only and referral-tree mechanics, paid-launch and supply pre-commitment tactics, market selection, anti-patterns, and the liquidity metrics to gate on. + +### 5. The Ceiling and the Moat + +**Core concept:** Growth always stalls. Rocketship curves are a sequence of S-curves, and each flattens against a ceiling: market saturation, channel degradation (CAC creep, banner blindness, viral fatigue), hard-side revolts, and quality collapse at scale — spam, overcrowding, context collapse. The moat is the network itself: defend the hard side, expect rivals to cherry-pick your densest segments, and remember that bundling fills the easy side but rarely wins the hard side. + +**Why it works:** Every acquisition channel decays as audiences habituate and competitors pile in — the first banner ads clicked through at double-digit rates; today's average is a fraction of a percent. Networks also degrade from within: scale attracts spam and collapses the intimate contexts that made early networks valuable, so quality work becomes growth work. And competition between networks is asymmetric: challengers win by applying atomic-network discipline to one underserved niche — which is exactly how incumbents get unbundled. + +**Key insights:** +- Plot growth as stacked S-curves; start the next curve (geography, segment, use case, product) before the current one flattens +- CAC creep and viral fatigue are laws, not failures — plan the next channel while the current one still works +- Watch for hard-side revolt signals: take-rate complaints, multi-homing, organized protest — the hard side leaves first and takes the network with it +- Quality interventions — curation, ranking, verification, spam fighting, sub-grouping — are growth investments at scale, not cost centers +- Defend against cherry-picking by over-serving your densest niches; that is precisely where a David will attack your Goliath +- Bundling buys distribution, not devotion — it fills seats on the easy side, while depth of engagement stays with whoever holds the hard side + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Stalled growth | Diagnose which ceiling hit first | Separate saturation, CAC creep, and quality-decay churn per network | +| Quality at scale | Fund trust and curation loops | Ratings, verification tiers, spam filters as a growth workstream | +| Competitive defense | Hold the hard side in dense niches | Match a rival's subsidies for top sellers before they multi-home | + +**Ethical boundary:** Fixing revolts and spam means addressing root causes for users — not silencing legitimate hard-side grievances with PR. + +See [references/scale-ceiling-moat.md](references/scale-ceiling-moat.md) when growth stalls or a rival appears — it runs the three forces as growth workstreams, diagnoses which ceiling hit first, and details quality interventions and cherry-picking defense at scale. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Launching to a market instead of a network | Users arrive scattered; nobody finds anybody | Pick one atomic network and saturate it | +| Counting signups instead of density | Vanity totals mask empty rooms | Measure weekly active networks, fill rate, time-to-match | +| Treating both sides equally | The hard side is the bottleneck and the flight risk | Build product and economics for the hard side first | +| Big-bang launch | Fast fill, weak networks; hype lands on emptiness | Tip network by network with a repeatable playbook | +| Faking scarcity or activity | Users discover the deception; trust collapses | Flintstone with real work; keep invite scarcity real | +| Cloning network #2 before #1 is stable | Replicating a broken loop multiplies failure | Gate expansion on magic-moment and retention bars | +| Assuming network effects strengthen forever | Spam, overcrowding, and context collapse compound too | Fund quality, trust, and curation as growth work | +| Ignoring cherry-picking rivals | Niche players peel off your densest segments | Over-serve dense niches; defend hard-side economics | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Can you name your first atomic network (who, where, how many)? | You're launching to a market, not a network | Constrain by geography, org, or interest until self-sustaining | +| Is the magic moment defined and instrumented? | You can't tell live networks from dead ones | Define it, measure it per network, gate expansion on it | +| Do you know who your hard side is and why they stay? | Supply churns and the easy side follows it out | Map money/status/utility motivations; build for them first | +| Does the product deliver value to its very first user? | Pure chicken-and-egg with no wedge | Add come-for-the-tool value or flintstone the gap | +| Is there a written playbook for tipping the next network? | Every launch is an expensive one-off bet | Codify invites, subsidies, and seeding from launch #1 | +| Are you measuring liquidity (fill rate, time-to-match)? | Growth optics hide network health | Add per-network density metrics to the core dashboard | +| Do you know which ceiling will hit first? | The stall will arrive as a mystery | Model saturation, CAC creep, and quality decay now | +| Is anything defending the hard side from rivals? | Cherry-pickers will peel off your best segments | Deepen hard-side economics and pro tooling | + +## Further Reading + +- [*"The Cold Start Problem: How to Start and Scale Network Effects"*](https://www.amazon.com/Cold-Start-Problem-Andrew-Chen/dp/0062969749?tag=wondelai00-20) by Andrew Chen +- [*"Platform Revolution"*](https://www.amazon.com/Platform-Revolution-Networked-Markets-Transforming/dp/0393249131?tag=wondelai00-20) by Geoffrey Parker, Marshall Van Alstyne & Sangeet Paul Choudary +- [*"Blitzscaling"*](https://www.amazon.com/Blitzscaling-Lightning-Fast-Building-Massively-Companies/dp/1524761419?tag=wondelai00-20) by Reid Hoffman & Chris Yeh + +## About the Author + +**Andrew Chen** is a general partner at Andreessen Horowitz, where he invests in consumer technology, and previously led the rider growth team at Uber. His long-running essay series on growth, metrics, and network effects — read across the tech industry — became the foundation for *The Cold Start Problem*. diff --git a/.agents/skills/cold-start-problem/references/atomic-networks.md b/.agents/skills/cold-start-problem/references/atomic-networks.md new file mode 100644 index 00000000..eba1f29a --- /dev/null +++ b/.agents/skills/cold-start-problem/references/atomic-networks.md @@ -0,0 +1,142 @@ +# Launching Atomic Networks + +## Table of Contents + +- [What an Atomic Network Is](#what-an-atomic-network-is) +- [Choosing the First Atomic Network](#choosing-the-first-atomic-network) +- [Minimum Size Logic](#minimum-size-logic) +- [Defining the Magic Moment](#defining-the-magic-moment) +- [Instrumenting the Magic Moment](#instrumenting-the-magic-moment) +- [Flintstoning: Filling the Empty Side](#flintstoning-filling-the-empty-side) +- [Single-Player Mode Fallbacks](#single-player-mode-fallbacks) +- [Sequencing Networks #2 Through #N](#sequencing-networks-2-through-n) +- [Atomic Network Launch Checklist](#atomic-network-launch-checklist) + +## What an Atomic Network Is + +An atomic network is the smallest network that is stable and self-sustaining: dense enough that the core interaction reliably happens, engaged enough that the group comes back without prompting, and complete enough to grow on its own. The test is simple and brutal: if you switched off all marketing, founder hustle, and paid incentives tomorrow, would this specific group still be using the product next week? + +Three properties define it: + +1. **Complete.** Every role the core interaction needs is present in the group. A messaging network needs senders and responders; a marketplace needs buyers plus enough sellers that searches return real options; a Q&A community needs askers and answerers. +2. **Stable.** The group's retention curve flattens instead of decaying to zero. People return because other people are there — not because a lifecycle email dragged them back. +3. **Self-sustaining.** Membership and activity hold or grow without continuous founder intervention. The network generates its own reasons to invite the next person. + +Why this is the unit of strategy: networked products below atomic size don't merely grow slowly — they actively repel users. Anti-network effects mean every visitor who finds an empty room becomes someone who "tried it and it was dead," and they rarely give you a second chance. Launching wide spreads your scarce early users thin and guarantees that every one of them experiences emptiness. Launching one atomic network concentrates them until the product actually works. + +Historical anchor: in 1958, Bank of America launched the first mass consumer credit card by mailing about 60,000 cards to one city — Fresno, California — where the bank already had relationships with both households and merchants. One city, both sides, instant density. That is the original atomic network launch: not "the US credit market," but "enough cardholders and merchants in Fresno that the card is usable on day one." + +## Choosing the First Atomic Network + +Constrain the launch until density is achievable with the resources you actually have. The four most useful constraint types: + +| Constraint | When to Use | Example | +|------------|-------------|---------| +| Geography | Physical-world products: rides, delivery, services, dating | One city — or one neighborhood, campus, or zip cluster | +| Organization | Workplace and collaboration products | One team inside one company, then the next team | +| Interest graph | Content, community, and commerce products | One obsessive niche: sneaker collectors, indie game designers | +| Event or moment | Products needing simultaneous adoption | A conference, a hackathon, a single party (Tinder's USC launch) | + +Score candidate networks 1-5 on each criterion and pick the highest total — not the biggest market: + +- **Density achievable.** Can you personally get 50-80% of this group onto the product within weeks? +- **Pre-existing relationships.** Do members already know, follow, or transact with each other? Existing graphs copy in fast. +- **Burning problem.** Is the current alternative painful enough that a janky v1 still wins? +- **Founder access.** Can you reach these people directly — by walking in, posting where they gather, or being one of them? +- **Tolerance for jank.** Early networks forgive missing features if the core interaction works. +- **Adjacency.** Are there ten or more similar networks next door for expansion (next campus, next city, next team)? + +Anti-criteria — reject networks chosen because the market is biggest there, the press lives there, investors will be impressed, or a partnership happened to fall into your lap. None of those produce density. + +Classic picks to calibrate against: Facebook started with one campus where a large share of students joined within weeks; eBay's earliest liquidity formed around collectibles traders who already obsessively bought and sold from each other; Tinder cracked USC by throwing a party where downloading the app was the price of entry — a few hundred socially connected students who all woke up with matches available. + +## Minimum Size Logic + +Every product has a magic number — the smallest network at which the experience works. Find yours by working backward from the experience, not forward from ambition: + +| Product | Atomic Size | Why | +|---------|-------------|-----| +| Zoom | 2 | One call between two people delivers full value | +| Slack | ~3 in one team | Enough conversation that checking the app pays off | +| Uber | Tens of drivers in one neighborhood | Enough supply that pickup times beat calling a taxi | +| Airbnb | ~300 listings, ~100 with reviews, per market | The internal threshold for a city to tip into self-sustaining growth | + +Derivation procedure: + +1. **Define the core transaction.** Message answered, ride matched, job filled, document co-edited, question answered. +2. **Set the acceptable-experience threshold from the user's view.** Pickup under ten minutes; a question answered within an hour; three or more relevant search results; a standup where most of the team posts. +3. **Compute the participants needed to hit that threshold at realistic activity rates.** If one in ten members answers on a given day and a good experience needs three answers, you need roughly thirty members. +4. **Buffer for lurking and churn.** Assume the 1/9/90 split between creators, contributors, and lurkers rather than uniform participation. +5. **That number is your atomic size — and smaller is better.** If the number exceeds what you can personally assemble, redesign the product (narrower use case, asynchronous value, single-player mode) until the number shrinks. + +## Defining the Magic Moment + +The magic moment is the experience that proves the network is working for this user: the car actually arrives; a teammate replies; the first booking lands; a stranger answers your question well. Write it as one sentence with four parts: + +> When **[actor]** does **[core action]**, **[counterpart response]** happens within **[time window]**. + +| Product Type | Magic Moment | +|--------------|--------------| +| Team chat | A new member posts and gets a reply from a teammate within minutes | +| Marketplace | A searcher finds 3+ relevant options and the order is accepted within the hour | +| Social/content | A first post earns real responses from people the poster cares about within a day | + +Equally important is the **zero** — the anti-magic moment: opening the app to an empty feed, posting into silence, searching and finding nothing. Zeroes are how networks die. Define your zero states as precisely as your magic moment, and treat the zero rate (the percentage of sessions that hit an empty state) as a first-class health metric. + +## Instrumenting the Magic Moment + +1. **Correlate.** Among your earliest users, find week-one behaviors that predict month-three retention. Classic illustrations: Slack found teams that exchanged about 2,000 messages stuck around; early Facebook drove every new user to ten friends in seven days. Yours will differ — derive it from your data rather than copying theirs. +2. **Pick the leading indicator.** One number per network — not per user — that marks the network as "live": for example, "5+ members active three days a week" or "fill rate above 80% for two consecutive weeks." +3. **Set the activation bar at the network level.** Users activate inside networks; a network activates when enough members hit the magic moment that the group sustains itself. +4. **Dashboard per network.** Aggregate metrics hide dead networks inside healthy averages. List every network (team, city, category) with a status: live, forming, or dead. +5. **Gate expansion.** No new network launches until the current cohort's live rate crosses your bar — for example, 60% of launched networks live at week eight. This is the discipline most teams skip. + +## Flintstoning: Filling the Empty Side + +In the cartoon, Fred Flintstone's car runs because his feet pedal under the chassis. Flintstoning is powering the product's missing side with manual human effort until the network can do the job itself: + +- **Founders as supply.** Reddit's founders seeded the front page with pseudonymous posts until the tone and volume attracted real contributors. DoorDash's founders took orders and drove the deliveries themselves. +- **Concierge matchmaking.** Manually pair the first buyers and sellers, mentors and mentees, guests and hosts — by phone, spreadsheet, and text message if necessary. +- **Hired or contracted supply.** Pay contractors to be available (drivers on guaranteed hourly rates, on-call tutors) so the easy side never sees a zero. +- **Imported content.** License, partner, or aggregate existing content so first sessions aren't empty — then taper as native contribution grows. + +Rules for honest flintstoning: + +1. The work must be real — real deliveries, real answers, real inventory. Faking counterparties, reviews, or activity is fraud against your own network, and it surfaces eventually. +2. Track the flintstoned share of transactions and set a declining target — for example, 80% manual in week two, under 10% by month four. +3. Build the replacement loop while you pedal: every manual match should teach you what the organic version needs. +4. Budget founder time explicitly. Flintstoning is a launch tactic with an exit, not an operating model. + +## Single-Player Mode Fallbacks + +"Come for the tool, stay for the network" is cold-start insurance: if the product is useful at n=1, the empty-network first session still delivers value, and every tool user is a future network node. Instagram's filters were a single-player photo tool that happened to feed a network; OpenTable gave restaurants an electronic reservation book before diners ever showed up; note-taking and pin-boarding products store value for one user that later becomes shareable. + +Design rules: + +- Pick a tool the hard side already needs — single-player utility doubles as hard-side acquisition. +- Design the empty first session deliberately: what does a user accomplish alone, today, before anyone else joins? +- Make network features amplify the tool rather than gate it. Sharing a document makes it better; requiring a team just to open it kills it. +- Surface the network at natural moments: place invite prompts where collaboration is the obvious next step of the solo workflow, not as interruptions. + +## Sequencing Networks #2 Through #N + +The first network proves the loop. The next nineteen prove the playbook. + +1. **Expand by adjacency.** The next networks should overlap the current one — neighboring campus, sister team, nearby zip codes, adjacent collector niche — so members, reputation, and supply spill over. +2. **Codify the launch kit.** Write down exactly what tipped network #1: seeding steps, flintstoning hours and budget, invite mechanics, subsidy levels, and the timeline to live status. The kit becomes the company's most valuable document. +3. **Gate on bars, not vibes.** Launch network #2 only when #1 holds its live bar without founder pedaling. Replicating a broken loop multiplies failure. +4. **Measure every network on one dashboard.** Same metrics, same bars, cohorted by launch date — so you can watch playbook efficiency improve. Time-to-live and cost-to-live should fall with every launch. +5. **Expect compounding.** Each successful network lowers the cost of the next through spillover awareness, reusable supply relationships, and refined messaging. Uber ran this as a literal city-launch playbook executed by local teams, hundreds of times. + +## Atomic Network Launch Checklist + +- [ ] First network named: who, where, how many (e.g., "the 60-person sales org at Acme," "dog owners in two zip codes") +- [ ] Atomic size derived from experience thresholds, not guessed +- [ ] Magic moment written in actor/action/response/time format +- [ ] Zero states defined and zero rate instrumented +- [ ] Network-level activation bar set; per-network dashboard exists +- [ ] Flintstoning plan with owners, budget, and a declining manual-share target +- [ ] Single-player value defined for the empty first session +- [ ] Hard side identified, with a recruiting plan for the first 10-50 +- [ ] Launch kit document started on day one +- [ ] Expansion gate written down: what must be true before network #2 diff --git a/.agents/skills/cold-start-problem/references/case-studies.md b/.agents/skills/cold-start-problem/references/case-studies.md new file mode 100644 index 00000000..398800b1 --- /dev/null +++ b/.agents/skills/cold-start-problem/references/case-studies.md @@ -0,0 +1,149 @@ +# Case Studies: Cold Start Principles in Practice + +## Table of Contents + +- [Case Study 1: A B2B Collaboration Tool Finds Its Atomic Network](#case-study-1-a-b2b-collaboration-tool-finds-its-atomic-network) +- [Case Study 2: Seeding a Local-Services Marketplace in One City](#case-study-2-seeding-a-local-services-marketplace-in-one-city) +- [Case Study 3: A Social App Recovers from a Big-Bang Launch](#case-study-3-a-social-app-recovers-from-a-big-bang-launch) +- [Key Takeaways](#key-takeaways) + +## Case Study 1: A B2B Collaboration Tool Finds Its Atomic Network + +### Context + +An eight-person startup builds an async standup and status tool, positioned "for modern engineering organizations." A directory launch and some press produce 2,400 signups in the first month. The team celebrates, then watches the retention chart. + +### The Problems + +**Almost everyone arrived alone.** 86% of signups came in with no teammates. They landed in an empty workspace, posted a status update nobody would read, and left. The product's entire value — seeing what your team is doing — was structurally impossible for them. + +**Activation was measured at the wrong level.** The team tracked "completed onboarding" (62% — looked great) while "invited 2+ teammates" sat at 9% and nobody owned it. Week-4 retention was 4%. + +**Sales chased the wrong unit.** Outbound targeted VPs of engineering at 500-person companies. Pilots stalled in procurement for months while the product sat unused — the company was selling to a market while the product needed a network. + +### The Application + +**Step 1: Define the atomic network.** Interviews with the handful of retained accounts showed the live unit was never a company. It was a single pod: a team lead plus four to eight engineers who already ran a daily standup ritual and merely wanted it async. The atomic network was defined as "one team where 4+ members post on 3+ days per week." + +**Step 2: Identify the hard side.** One person per pod did the work: the team lead who set the tool up, configured prompts, and nagged everyone to post. Their motivations were utility (kill the standing meeting) and status (look organized to their own manager). The roadmap was rebuilt for the lead first: one-click setup, a blockers digest, and an auto-generated weekly summary the lead could forward upward. + +**Step 3: Define and instrument the magic moment.** "A standup where every member posts before 11am and the lead reacts to at least one update." Data check: teams with three consecutive such standups in week one retained at five times the rate of other teams. That became the network-level activation bar on a per-pod dashboard with live/forming/dead statuses. + +**Step 4: Rebuild onboarding around the network.** Signup now asks for the team by name and email up front (graph capture), and the first-run experience is built for inviting the pod. For leads who genuinely arrive alone, a single-player fallback — a personal work journal that compiles a weekly self-report — delivers standalone value while they recruit. + +**Step 5: Flintstone the first pods.** Founders joined the first 40 workspaces as visible "facilitators": posting prompt questions, modeling good updates, and personally onboarding every member. Manual, unscalable, and decisive — these pods set the usage patterns the templates were later copied from. + +**Step 6: Sequence expansion by adjacency.** A company "tips" when three or more pods are live; at that point the lead's peer teams are the next targets, and a cross-pod dashboard (the org-level product) is offered to engineering managers — the economic step. + +### Results After 4 Months + +| Metric | Before | After | +|--------|--------|-------| +| Network-level activation | 9% invited anyone | 47% of new workspaces reach 4+ active members | +| Week-4 retention | 4% of users | 58% of activated pods still active | +| Weekly active pods | Not measured | 212 | +| Multi-pod companies | 0 | 31 with 3+ live pods | +| Founder flintstoning time | 0 | 15 hrs/week at start → 3 hrs/week by month 4 | + +### Lessons Learned + +1. The atomic network was smaller and more specific than anyone guessed — not a company, not a department, but a pod with an existing ritual to replace. +2. User-level activation metrics hid everything; the pod-level bar made dead workspaces visible in one glance. +3. The single-player journal looked like a distraction and was the bridge that kept solo leads alive long enough to assemble their pods. +4. The hard side wasn't paid in money. The forwardable weekly summary — status with their own manager — retained leads better than any feature shipped that quarter. + +## Case Study 2: Seeding a Local-Services Marketplace in One City + +### Context + +A home-cleaning marketplace raises $1.2M and launches in three cities simultaneously, splitting the marketing budget evenly. The model: customers book online, vetted cleaners accept jobs, the platform takes 20%. + +### The Problems + +After eight weeks: fill rate 38%, median time-to-match 19 hours, and 41% of first-time customers never returned — most had experienced a no-match or a next-day response to a same-week need. Cleaners were churning too: with demand spread thin, the median provider got two jobs a week, far below what justified keeping the app on their phone. Paid CAC was climbing as bad reviews accumulated. Both sides were starving in all three cities at once — three sub-atomic networks, each generating anti-network effects. + +### The Application + +**Step 1: Retreat to one city, then one zone.** A selection scorecard (provider availability, density potential, competitive gap, ops reach) picked the strongest city — not the largest — and constrained the relaunch further to four contiguous zip codes. + +**Step 2: Pre-commit supply.** Thirty-five vetted cleaners signed before relaunch: $25/hour guaranteed for eight weeks plus a fee holiday, in exchange for defined availability windows and a two-hour response SLA. The taper was published in the contract: the guarantee steps down as utilization crosses 60%. + +**Step 3: Throttle demand to supply.** Paid acquisition was geofenced to the four zips and capped so fill rate stayed above 85%. Customers elsewhere hit a waitlist: "We'll text you when your zip code opens." Marketing protested; the founders held the cap. + +**Step 4: Flintstone operations.** Founders dispatched edge cases manually, handled every reschedule, and called each customer after their first clean. Every manual fix was logged as a requirement for the matching system. + +**Step 5: Gate expansion on liquidity bars.** Written definition of "tipped": fill rate above 85% for two consecutive weeks, time-to-match under two hours, 30-day repeat rate above 45%, and a guarantee gap at zero. Adjacent zips opened only when the current zone held all four bars. + +**Step 6: Codify the launch kit.** Seeding sequence, subsidy levels, taper schedule, geofence caps, and dispatch scripts were written up and rerun in city #2 by one ops hire. + +### Results After 6 Months + +| Metric | 3-City Launch (Week 8) | One-Zone Relaunch (Week 8) | City #2 via Kit (Week 8) | +|--------|------------------------|----------------------------|--------------------------| +| Fill rate | 38% | 91% | 87% | +| Median time-to-match | 19 h | 1.4 h | 1.9 h | +| 30-day repeat rate | 22% | 51% | 48% | +| Median provider jobs/week | 2 | 9 | 8 | +| Guarantee cost per booking | — | $11 → $2 | $6 → $1 | +| Cost to tip the market | Never tipped | $86K | $52K | + +### Lessons Learned + +1. Throttling demand felt insane and was the highest-leverage decision: every early customer landed on full shelves, and repeat rate — not signups — is what compounds. +2. Supply pre-commitment turned launch from a gamble into logistics; day one had inventory because it was signed before marketing spent a dollar. +3. The published taper prevented a provider revolt at step-down — cleaners had priced it in, and by then organic demand had closed the gap. +4. The playbook compounded: city #2 tipped 40% cheaper and faster, with zero founder dispatching. The durable asset of the relaunch was the kit. + +## Case Study 3: A Social App Recovers from a Big-Bang Launch + +### Context + +A social app for runners — activity sharing plus local route and crew discovery — lands a press exclusive and an influencer campaign. 340,000 installs in 17 days. Champagne, then silence. + +### The Problems + +**The cohort died on arrival.** D1/D7/D30 retention: 31% / 9% / 2.8%. The median new user followed one account. 74% of posts received zero responses. The zero rate — sessions opening to an empty or stale feed — was 63%. + +**Aggregate dashboards hid it for two weeks.** Installs and signups kept climbing while every cohort beneath them collapsed. Users had arrived as 340,000 scattered individuals, not as networks; each one experienced a ghost town, and anti-network effects did the rest — "I tried it, it was dead." + +**The press card was spent.** A relaunch blast was impossible; the market had already formed its opinion once. + +### The Application + +**Step 1: Rebuild analytics at the network level.** The team defined the candidate atomic network — a local running club or crew with roughly ten members posting weekly — and reprocessed the wreckage. Finding: 14 accidental live clusters, all crews that had joined together, were essentially the only retained users. The product was club-first; it had been launched follower-first. + +**Step 2: Relaunch invite-only around clubs.** Signup now requires joining or creating a club. Solo signups go to a waitlist keyed by city and crew name — graph capture that turned the dead install base into a seeding map. + +**Step 3: Solve the hard side: club captains.** Captains (status + utility motives) got dedicated tools — run scheduling, attendance, a member map, a public club page — plus a founding-captain badge and a monthly call with the team. The founders personally recruited 25 captains across three running-dense cities with a status pitch: "your crew's home online." + +**Step 4: Define the magic moment and the bars.** Magic moment: "your post gets 3+ responses from your own club within 24 hours." Club live bar: 10+ weekly posters. Expansion gate: a new city opens only when 60% of launched clubs are live. + +**Step 5: Flintstone and add single-player value.** Staff seeded route content and event recaps into young clubs, and the app shipped solid solo run-tracking so a runner waiting for their club still got tool value (come for the tool, stay for the network). + +**Step 6: Re-engage the dead installs club by club.** The 340K lapsed users were contacted city by city as their clubs went live — "12 crews are now active in Austin, including one near you" — never as another blast. + +### Results After 5 Months + +| Metric | Big-Bang (Day 30) | Club Relaunch (Month 5) | +|--------|-------------------|-------------------------| +| Live networks | ~14 accidental clusters | 187 live clubs of 240 launched | +| D30 retention | 2.8% | 38% among club members | +| Zero rate | 63% | 11% | +| Posts receiving responses | 26% | 81% | +| Organic share of new users | 8% | 64% via club invites | +| Weekly actives | 9K and falling | 31K and growing | + +### Lessons Learned + +1. The launch wasn't under-marketed — it was over-marketed into emptiness. Density, not awareness, was the binding constraint, and press multiplied the anti-network effect. +2. Requiring club membership at signup looked like friction and was the retention mechanism: nobody lands alone anymore. +3. Captains were the network. Tooling and status for roughly 240 people moved 31,000 weekly actives. +4. The first launch's one real asset was data: the 14 accidental clusters revealed exactly what the atomic network was. Post-mortems on dead cohorts are seeding maps. + +## Key Takeaways + +1. **Define the network before the funnel.** All three teams measured users while the product lived or died at the network level — pods, zip codes, clubs. Per-network dashboards with live/forming/dead statuses changed every decision downstream. +2. **The hard side is specific and small.** A team lead, 35 cleaners, 240 captains — single-digit-percentage minorities determined everything. Build their tools, economics, and status first. +3. **Throttle to density.** The counterintuitive moves — capping demand, gating signups, waitlists, invite-only — created the liquidity that made every first impression work. Growth restraint was the growth tactic. +4. **Bars before expansion.** Written live bars (fill rate, club live rate, pod participation) turned "are we ready to grow?" from a debate into a checklist, and made the circuit breaker impersonal. +5. **Playbooks compound.** Each tipped network made the next one cheaper. The durable output of a launch is the kit and the bars — the cohort is just the first proof. diff --git a/.agents/skills/cold-start-problem/references/hard-side.md b/.agents/skills/cold-start-problem/references/hard-side.md new file mode 100644 index 00000000..871a7309 --- /dev/null +++ b/.agents/skills/cold-start-problem/references/hard-side.md @@ -0,0 +1,123 @@ +# Solving the Hard Side + +## Table of Contents + +- [Why Every Network Has a Hard Side](#why-every-network-has-a-hard-side) +- [Identifying Your Hard Side](#identifying-your-hard-side) +- [Motivation Mapping: Money, Status, Utility](#motivation-mapping-money-status-utility) +- [Playbook 1: Come for the Tool](#playbook-1-come-for-the-tool) +- [Playbook 2: Content and Status First](#playbook-2-content-and-status-first) +- [Playbook 3: Economic Subsidies](#playbook-3-economic-subsidies) +- [Pro Features: Retaining the Hard Side](#pro-features-retaining-the-hard-side) +- [Balancing Both Sides](#balancing-both-sides) +- [Hard-Side Health Metrics](#hard-side-health-metrics) + +## Why Every Network Has a Hard Side + +Participation in networks is wildly unequal. The long-observed 1/9/90 rule says roughly 1% of users create most of the content, 9% contribute occasionally, and 90% consume. A small fraction of Wikipedia's editors write most of the encyclopedia; a sliver of sellers moves most marketplace volume; a minority of drivers supplies most rides. That minority is the hard side: they do disproportionate work, they extract (and deserve) disproportionate value, and they are disproportionately hard to acquire and keep. + +The hard side is hard for structural reasons: + +- **Their work is costly.** Creating, listing, hosting, and driving take real time, skill, and risk. Consuming takes a thumb. +- **They have alternatives.** Anyone doing this work seriously is courted by every rival network and can multi-home with a second app in their pocket. +- **Their expectations are professional.** They need reliable earnings, audience growth, or workflow efficiency — not novelty. +- **Their absence is fatal.** When the hard side thins out, the easy side meets empty shelves and silent feeds, and quietly leaves without telling you why. + +The strategic consequence: court the hard side first, build for them first, and defend them hardest. The easy side follows value; the hard side creates it. + +## Identifying Your Hard Side + +Ask three questions of your network: + +1. **Without whom is the product an empty room?** Mentally remove each role; the one whose removal kills the experience first is the hard side. +2. **Who does work, not just consumption?** Listing, scheduling, creating, answering, organizing, configuring. +3. **Whose churn predicts network death?** In your data, which role's week-four retention best predicts whether the whole network is alive at month six? + +| Network Type | Easy Side | Hard Side | The Work They Do | +|--------------|-----------|-----------|------------------| +| Ride-hailing / delivery | Riders, eaters | Drivers, couriers | Supply hours, asset risk, coverage | +| Commerce marketplace | Buyers | Sellers, power sellers | Inventory, listings, fulfillment, service | +| Content / social | Viewers, lurkers | Creators | Continuous content production | +| Q&A / community | Readers, askers | Expert answerers, moderators | Answers, curation, norm enforcement | +| Workplace collaboration | Invited teammates | The organizer / team lead | Setup, configuration, pulling others in | +| Home services | Homeowners | Providers (cleaners, plumbers) | Jobs completed, scheduling, quality | + +Note the workplace case: the hard side isn't paid. It's the one person who sets up the tool, configures it, and drags everyone else in. B2B cold starts live or die on whether that organizer wins. + +## Motivation Mapping: Money, Status, Utility + +Interview 10-20 members of your hard side. For each, rank the three core motivations, then check whether the product actually invests in the top one. + +| Motivation | Who It Drives | What They Ask | What to Build | Failure Mode If Ignored | +|------------|---------------|---------------|---------------|-------------------------| +| Money | Drivers, sellers, hosts, freelancers | "What will I earn per hour, and when do I get paid?" | Transparent effective earnings, fast payouts, clear fees, demand forecasts | Multi-homing; defection to whoever pays 5% more | +| Status | Creators, reviewers, experts, early adopters | "Will I be seen? Can I grow faster here than elsewhere?" | Follower growth, distribution boosts for early quality work, badges, featuring | Quiet decay: creators post where the reach is | +| Utility | Organizers, professionals with a job to do | "Does this make my actual work easier today?" | Single-player workflow tools, time savings, integrations | Tool abandoned before any network forms | + +Three rules: + +- Most hard sides blend motivations, but one dominates per segment. Segment by dominant motive, not demographics. +- Early networks over-index on status and utility — money arrives when volume exists. Give first movers an explicit early-adopter advantage: outsized reach, founding-member badges, grandfathered economics. +- Revisit the map as you scale. Hobbyists professionalize, and yesterday's status-driven creator is today's income-dependent professional with money anxieties. + +## Playbook 1: Come for the Tool + +Build a single-player tool the hard side already needs; layer the network on top. + +1. **Find the workflow pain adjacent to your network.** Restaurants kept paper reservation books (OpenTable's wedge was replacing them); photographers wanted better-looking photos (Instagram's filters); writers needed publishing and payments before they needed an audience platform. +2. **Ship the tool and judge it purely as a tool.** Would this person use it with zero network attached? If not, the wedge is fake. +3. **Add network features that make the tool better, not gated.** The reservation book fills itself from online diners; the photos gain an audience; the newsletter gains discovery and recommendations. +4. **Time the ask.** Prompt invites and cross-side participation at the moment the network step is the natural next action of the solo workflow — publishing, sharing, scheduling — not as a signup wall. + +When it works: the hard side's workflow is genuinely underserved and your tool is honestly better. When it fails: the tool is a thin pretext to trick people into a network, and they smell it in the first session. + +## Playbook 2: Content and Status First + +For status-driven hard sides — creators, experts, tastemakers — pay in the currency they actually want: distribution and recognition. + +- **Seed with a curated cohort.** Hand-pick 50-200 creators whose work defines the culture you want, and onboard them personally, white-glove. +- **Engineer early reach.** New networks have low competition for attention — make that the explicit pitch: "your post is seen by ten times more people here than on the incumbent." +- **Build recognition systems.** Featuring, leaderboards, verified and expert tiers, "founding creator" labels that persist for life. +- **Run programs with budgets.** Creator funds, revenue shares, and grants work — but pair money with reach. Money alone rents creators; reach retains them. +- **Protect quality over quantity.** A hundred excellent contributors set norms that ten thousand mediocre ones will follow. Curation early is culture later. + +## Playbook 3: Economic Subsidies + +For money-driven hard sides, manufacture the economics of a liquid network before liquidity exists: + +- **Earnings guarantees.** "$X per hour for your first N weeks." You pay the gap between the guarantee and organic earnings; the gap shrinks automatically as real demand arrives. +- **Sign-up and milestone bonuses.** For completing setup, first listing, first ten jobs — pay for activation behaviors, not bare registration. +- **Fee holidays.** Zero take-rate at launch with a published step-up schedule. +- **Onboarding subsidies.** Cover the costs that block participation: equipment kits, professional photography, background checks, insurance. + +Treat subsidies as supply-side CAC. The management metrics are cost per retained active supplier, payback period, and the taper curve. Two integrity rules: publish the taper schedule in advance — surprise rollbacks read as betrayal and trigger revolts — and never market subsidized earnings as if they were organic. + +## Pro Features: Retaining the Hard Side + +The hard side professionalizes quickly; retention means growing with them. Sequence these for month three of a network's life, not year three: + +- **Power workflows.** Bulk listing and editing, scheduling, templates, keyboard-speed interfaces for people who use the product hours per day. +- **Analytics.** Earnings and audience dashboards, conversion funnels, benchmarks against similar suppliers or creators. +- **APIs and integrations.** Accounting, inventory, calendars, cross-posting — meet professionals inside their existing stack. +- **Tiered status programs.** Superhost-style tiers with objective criteria and real benefits: ranking boosts, lower fees, priority support, early features. Review on a published cycle. +- **Capital and protection.** Instant payouts, cash advances, damage protection, insurance. These deepen dependence honestly — by genuinely de-risking the hard side's business. + +## Balancing Both Sides + +- **Manage a target ratio per network, not globally.** Riders per driver, viewers per creator, buyers per seller — each market or segment has its own balance point. +- **Throttle the easy side when liquidity slips.** Pause demand marketing in any network where fill rate or response rate drops below the bar. Nothing churns the easy side like ordering into a void — and nothing churns the hard side like silence after they've committed. +- **Move subsidy budget dynamically.** Spend on whichever side is scarce in each network this month; scarcity flips as networks mature. +- **Watch for hard-side oversupply too.** Too many sellers chasing too few buyers craters per-supplier earnings and drives out your best people first — they're the ones with options. + +## Hard-Side Health Metrics + +| Metric | Definition | Watch For | +|--------|------------|-----------| +| Hard-side retention curve | % of new suppliers/creators still active at weeks 4 / 12 / 26 | Decay that never flattens | +| Effective earnings or reach | Dollars per hour after costs; responses or views per post | Decline as the network grows (overcrowding) | +| Utilization | % of offered supply hours or inventory that transacts | Low = oversupply; very high = shortages and easy-side pain | +| Concentration | Share of volume from the top 1% / 10% of the hard side | Fragility — a handful of defections can kill a network | +| Multi-homing rate | % of the hard side also active on rivals (survey or panel) | Rising = your moat is rented, not owned | +| Time-to-first-earnings | Days from signup to first payout, booking, or real audience response | This is the hard side's activation moment; shrink it relentlessly | + +Review these per network, cohorted by launch date, alongside the easy side's funnel — a healthy hard side with a starving easy side is just a different way to die. diff --git a/.agents/skills/cold-start-problem/references/scale-ceiling-moat.md b/.agents/skills/cold-start-problem/references/scale-ceiling-moat.md new file mode 100644 index 00000000..a37eceb8 --- /dev/null +++ b/.agents/skills/cold-start-problem/references/scale-ceiling-moat.md @@ -0,0 +1,105 @@ +# Escape Velocity, the Ceiling, and the Moat + +## Table of Contents + +- [Escape Velocity Is an Operating Model](#escape-velocity-is-an-operating-model) +- [Workstream 1: The Acquisition Effect](#workstream-1-the-acquisition-effect) +- [Workstream 2: The Engagement Effect](#workstream-2-the-engagement-effect) +- [Workstream 3: The Economic Effect](#workstream-3-the-economic-effect) +- [Diagnosing the Ceiling](#diagnosing-the-ceiling) +- [Quality Interventions at Scale](#quality-interventions-at-scale) +- [Moat Strategy: Network vs. Network](#moat-strategy-network-vs-network) +- [Competitive Defense Checklist](#competitive-defense-checklist) + +## Escape Velocity Is an Operating Model + +From the outside, hypergrowth looks like one unstoppable force. From the inside, it is three distinct effects that must each be deliberately amplified — and they map naturally onto the growth organization. Staff each as a named workstream with an owner, a core metric, and a lever backlog: + +| Workstream | What It Amplifies | Core Metric | Typical Levers | +|------------|-------------------|-------------|----------------| +| Acquisition effect | The network acquiring its next users | Viral factor; % organic new users; CAC payback | Invite flows, referral incentives, contact sync, shared artifacts | +| Engagement effect | Value per user rising with density | Frequency and retention, by cohort and by network density | Notification quality, re-engagement loops, engagement ladders, new use cases | +| Economic effect | Unit economics improving with density | Conversion to paid, take rate, subsidy share | Pricing, premium tiers, subsidy rollback, match efficiency | + +The point of the model: when growth slows, you can localize which effect weakened — instead of throwing generic tactics at an aggregate chart. + +## Workstream 1: The Acquisition Effect + +Network-driven acquisition means the product spreads through use, not just through ads: + +- **Map every viral loop explicitly:** new user → experiences value → exposes others (invite, share, visible artifact) → some fraction converts → repeat. Measure conversion at each step, per loop; fix the weakest step first. +- **Maintain a loop inventory.** Direct invites ("your teammate added you"), collaboration handles (docs and boards shared outward), public artifacts (profiles, listings, videos with attribution), contact-sync prompts. Each loop has its own math. +- **Know your viral factor.** New users generated per existing user per period: even 0.4-0.7 dramatically cuts blended CAC; above 1.0 is rare and temporary, so don't build the plan on it. +- **Use paid as ignition, not as a substitute.** Route paid users into live networks via geo and segment targeting; paid traffic dumped into sparse networks buys zero-state sessions and churn. + +## Workstream 2: The Engagement Effect + +Density should raise the value of every session — but only if you engineer the loops that realize it: + +- **Reinforcing loops.** Notifications that represent real human activity — a reply, a booking, a follow — are the network talking. System-generated nags are spam wearing the network's clothes; keep the ratio honest or users mute everything. +- **Engagement ladders.** Define the path from lurker → contributor → power user for each side, and build prompts and rewards that move users exactly one rung: first post, first sale, first integration. +- **Re-engagement keyed to network events.** Dormant users return for things they care about — "your friend joined," "your question got an answer," "demand spiked in your area" — not for calendar-based blasts. +- **Cohort by density.** Retention analyzed by the density of the network a user joined (live network vs. landed alone) tells you whether to fix the product or fix the routing. +- **Add adjacent use cases.** New jobs raise frequency — payments inside chat, scheduling inside listings. Frequency is the engagement moat. + +## Workstream 3: The Economic Effect + +As density rises, monetization should get easier. Measure and harvest it deliberately: + +- **Track conversion against per-network density.** Buyers who find a match convert to paid plans; creators with real audiences buy pro tools. If conversion isn't rising with density, the premium offer is mispriced or mistargeted. +- **Roll back subsidies as the scale dividend.** As organic liquidity replaces manufactured liquidity, taper guarantees and discounts on the published schedule, and redirect the budget to the next S-curve. +- **Move take-rates only with added value.** Payments, insurance, financing, promotion, and distribution justify a higher cut; raising fees without new value is the classic revolt trigger. +- **Put premium tiers on the hard side first.** Pro tools, analytics, and promotion monetize the side whose willingness to pay tracks their earnings. +- **Watch for negative economic loops.** Funding CAC with price increases, or growing ad load until it crowds out content, flatters this quarter while degrading the network underneath. + +## Diagnosing the Ceiling + +Growth always flattens; the skill is reading which ceiling you hit. Rocketship growth is a sequence of S-curves — each one saturates, and the next must already be starting when it does. + +| Symptom | Likely Ceiling | Confirming Test | Intervention | +|---------|----------------|-----------------|--------------| +| New-user growth slows, CAC steady | Saturation of current networks | Penetration % of addressable members per network | Start the next S-curve: new geography, segment, or use case | +| CAC climbing, channel CTRs decaying | Channel degradation | Channel-level CTR and CAC trend lines | Incubate new channels early; shift weight to product loops | +| Signups fine, activation falling | New users landing in sparse or dead networks | Activation rate by network density | Route users to live networks; revive or merge dead ones | +| Engagement per user falling at scale | Overcrowding and context collapse | Posting rate of long-tenured users; response rates | Sub-groups, channels, ranking, audience controls | +| Quality complaints, scammy content | Spam loops — incentives attracting bad actors | Spam reports per 1,000 sessions; fraud rate | Trust and safety as growth work; rate limits; verification | +| Hard-side churn, organized complaints | Network revolt over economics or policy | Multi-homing rate; take-rate sentiment; community forums | Real economic fixes plus voice channels, not PR | +| Sudden regional or legal drops | Regulatory or trust shock | Policy mapping; press monitoring | Compliance, proactive trust features, geographic strategy | + +Channel degradation deserves emphasis because it is a law, not a mistake: every marketing channel decays as audiences habituate and competitors pile in. The first banner ads clicked through at double-digit rates; the format now averages well under a tenth of a percent. The same decay curve hits each new channel, just faster. Plan for it: keep a channel portfolio with explicit next-channel incubation, and treat product-driven loops (which decay slower) as the backbone. + +Context collapse is the subtler engagement ceiling: when one feed serves every audience a person has — friends, family, coworkers, strangers — people stop posting authentic content because no single post fits all contexts. Posting shifts to broadcasters and professionals, and the network drifts from "my people" to "media." Watch the posting rate of ordinary, long-tenured users as the early-warning metric. + +## Quality Interventions at Scale + +Scale degrades quality by default; these interventions restore it without strangling growth: + +- **Ratings and reviews with teeth.** Two-sided ratings, recency weighting, minimum-volume gates, and real consequences (ranking, removal) — calibrated so a 4.6 actually means something. +- **Verification tiers.** Identity, credential, and quality verification for the hard side; badges the easy side can trust at a glance. +- **Ranking over chronology.** Feeds and search that favor relevance and quality as volume explodes, with engagement-bait explicitly demoted. +- **Friction for abusers, none for the good.** Rate limits, new-account probation periods, and small posting costs applied where spam clusters — invisible to normal users. +- **Pruning.** Archive zombie listings, dead groups, and stale content that create false density and bad matches. +- **Context restoration.** Groups, channels, close-friends modes, and ephemeral formats rebuild the intimacy that made early networks valuable. +- **Moderation with status.** Recruit the community's natural moderators and pay them in recognition, tools, and authority. + +## Moat Strategy: Network vs. Network + +At scale, competition is rarely product versus product — it is network versus network, fought sub-network by sub-network: + +- **The moat is density, not features.** Features are copied in a quarter; a dense, retained network is not. Defensibility means continuing to win each niche's hard side, forever. +- **Expect cherry-picking.** Rivals won't attack everywhere at once; they will apply atomic-network discipline to your most profitable, densest, or most neglected segment — exactly how Craigslist was carved into a dozen vertical startups. Run the audit on yourself: which of our segments would make a great startup? +- **David usually beats Goliath in the niche.** The focused attacker offers that niche's hard side better economics, better tools, and more status than a generalist can. As the incumbent, over-serve your dense niches before someone else does: dedicated teams, niche-specific features, defended economics. +- **Fight on the hard side.** Match or beat rival subsidies for your top suppliers and creators before they multi-home. Lock in honestly — earned reputation, seniority benefits, capital, insurance — rather than punitive exclusivity clauses that breed resentment and regulator attention. +- **Bundling is real as distribution, overrated as offense.** A bundler shipping your category inside an existing product gets reach and default placement, but it wins only if it also holds the hard side. As the challenger, out-love the hard side where the bundler is shallow; as the bundler, staff the new category like a startup or watch engagement stay shallow. +- **Multi-homing is the leading indicator.** When your hard side runs two apps, the moat is draining — move while it is multi-homing, before it becomes exclusive defection. + +## Competitive Defense Checklist + +- [ ] Quarterly per-niche density audit: where are we dense, sparse, profitable, neglected? +- [ ] Multi-homing tracking for the top 10% of the hard side (survey or panel data) +- [ ] Rival subsidy and fee tracker, refreshed monthly +- [ ] Win/loss interviews with hard-siders who left or reduced activity +- [ ] A named owner for each dense niche a rival could cherry-pick +- [ ] Next S-curve portfolio: 2-3 staffed bets before the current curve flattens +- [ ] Revolt early-warning review: hard-side forum sentiment, support themes, take-rate complaints +- [ ] Quality dashboard (spam rate, zero rate, response rates) reviewed in the growth meeting, not in a separate silo diff --git a/.agents/skills/cold-start-problem/references/tipping-playbooks.md b/.agents/skills/cold-start-problem/references/tipping-playbooks.md new file mode 100644 index 00000000..89d27ad6 --- /dev/null +++ b/.agents/skills/cold-start-problem/references/tipping-playbooks.md @@ -0,0 +1,135 @@ +# Tipping Playbooks + +## Table of Contents + +- [From One Network to a Repeatable Playbook](#from-one-network-to-a-repeatable-playbook) +- [Invite-Only Mechanics](#invite-only-mechanics) +- [Designing the Waitlist](#designing-the-waitlist) +- [Paying Up: Subsidies and Guarantees](#paying-up-subsidies-and-guarantees) +- [Supply Pre-Commitment](#supply-pre-commitment) +- [Picking the Next Market](#picking-the-next-market) +- [Anti-Patterns](#anti-patterns) +- [Measuring Tipping: Liquidity Metrics](#measuring-tipping-liquidity-metrics) +- [The Expansion Checklist](#the-expansion-checklist) + +## From One Network to a Repeatable Playbook + +The tipping point is the stage where launching new networks shifts from heroic one-off effort to repeatable process — each market, campus, or segment tips faster and cheaper than the last because the playbook, brand spillover, and supply relationships compound. The deliverable of this stage is not a growth number; it is a **launch kit**: the documented sequence that took network #1 from zero to self-sustaining, ready to run against networks #2 through #N. + +A launch kit contains: + +- The target-network selection scorecard and the data behind the last pick +- The seeding sequence with owners and timelines (who recruits the hard side, in what order) +- Flintstoning hours and budget actually spent, by week +- Invite mechanics, referral rewards, and the copy that worked +- Subsidy levels with the taper schedule and the observed guarantee gap over time +- The liquidity bars that define "tipped" for one network +- The timeline and cost of every prior launch, for comparison + +## Invite-Only Mechanics + +Invite-only looks like marketing scarcity; it is actually network construction. It does three jobs at once: + +1. **Density by design.** Every new user arrives knowing at least one person inside — their inviter. Invites travel along real social graphs, so the network copies itself in clusters instead of random scatter. +2. **Curation.** Early users define culture and quality. Gating membership lets you choose who sets the norms, and keeps spam out while you are too small to fight it. +3. **Scarcity and social proof.** Outsiders see something worth queuing for, and every invite arrives as a personal endorsement rather than an ad. + +Parameters to tune: + +| Parameter | Starting Point | Tuning Signal | +|-----------|----------------|---------------| +| Invites per user | 3-5 | Raise for high-quality, well-connected cohorts; cut if quality drops | +| Earn-more rule | Active users unlock more invites | Reward contribution, not bare signup | +| Cohort release | Admit by cluster (team, city, community), not first-come-first-served | Singles admitted alone hit zeroes; clusters arrive live | +| Vouching | Inviter standing affected by invitee behavior | Spam appearing → tighten vouching | +| Gates | Geographic or segment caps to protect liquidity | Don't admit demand where supply isn't ready | + +Calibration classics: Gmail spread through scarce invites that people traded and begged for; Facebook gated campus by campus and didn't open general registration until the model was proven; the same mechanics get rerun by every breakout social app. The point teams miss: process the waitlist by network cluster, never by signup order. + +## Designing the Waitlist + +1. **Capture the graph at signup.** Company domain, city, school, club, interest — whatever defines your atomic network unit. A waitlist without graph data is just a mailing list. +2. **Score clusters, not individuals.** Admit a cluster when it can form an atomic network on arrival — for example, eight or more people from one team, or two hundred in one zip code. +3. **Let applicants move themselves up by recruiting their cluster.** "Get three coworkers on the list and skip ahead" turns the waitlist into a seeding engine. +4. **Communicate honestly.** Show position, expected wait, and exactly what unlocks access. A silent or fake queue burns the trust you are trying to manufacture. +5. **Instrument the referral tree.** Track who invited whom, conversion per branch, and which super-inviters' branches retain best — those people are your future community hires and ambassadors. + +## Paying Up: Subsidies and Guarantees + +When organic density would take too long, buy it. Money converts into liquidity — the one asset competitors cannot copy-paste. + +- **Earnings guarantees (supply side).** Pay the gap between guaranteed and organic earnings; the cost falls automatically as real demand arrives. Uber's launch playbook leaned on driver guarantees so riders never saw an empty map. +- **Demand-side coupons.** First-order discounts, time-boxed to launch. Design them to create a habit (three uses) rather than a single trial. +- **Fee holidays and reduced take-rates** for launch cohorts, with a published step-up schedule. +- **Hero subsidies.** Overpay a handful of anchor suppliers — the famous restaurant, the prominent creator — whose presence pulls both sides in. + +Manage it like CAC: + +| Metric | Definition | Healthy Direction | +|--------|------------|-------------------| +| Cost per tipped network | Total subsidies ÷ networks reaching the live bar | Falling with each launch | +| Guarantee gap | Guaranteed minus organic earnings per supplier | Trending to zero by week 8-12 | +| Subsidized share | % of transactions touched by any subsidy | Declining on schedule | +| Post-taper retention | Supply and demand retention after subsidies step down | Flat curve = real network; cliff = rented usage | + +Integrity rules: publish taper schedules up front, and never book subsidized activity as evidence of organic product-market fit — you will fool your own roadmap before you fool anyone else. + +## Supply Pre-Commitment + +For marketplaces, sign the hard side before demand launch so day one has full shelves: + +1. **Set the supply bar from your liquidity targets.** Example: 40 vetted providers are required for a sub-two-hour time-to-match in one zip cluster at projected demand. +2. **Pre-sign with commitments in both directions.** Guaranteed earnings or fee holidays in exchange for defined availability windows and response-time SLAs. +3. **Stage onboarding before opening demand.** Profiles, photos, background checks, payment details — done before the first customer searches. +4. **Open demand gradually.** Waitlist or geofence customers so the fill rate stays above bar from the first hour. A launch where the first hundred customers all get served beats one where a thousand try and half fail. + +## Picking the Next Market + +Score candidates 1-5 on each criterion; expand to the top scorer, not the biggest: + +| Criterion | Question | +|-----------|----------| +| Adjacency | Does it border (geographically or socially) a tipped network, so awareness and members spill over? | +| Density potential | Can we hit atomic size with known playbook effort? | +| Hard-side availability | Is supply discoverable and recruitable — existing pros, creators, organizers? | +| Competitive gap | Is the incumbent weak, absent, or neglecting this segment? | +| Economics | Do unit economics work at this market's price points and behavior? | +| Operational reach | Can we staff, visit, and support it without heroics? | + +## Anti-Patterns + +- **The big-bang launch.** Maximum simultaneous awareness — press exclusives, TV, launch-day stunts — fills the product faster than density can form. Hundreds of thousands of strangers land in empty rooms, churn, and immunize the market against your second chance. Google+ is the canonical corpse: hundreds of millions of registered users, almost no live networks, eventually shut down. Rule: press is for harvesting demand into networks that already work, not for creating networks. +- **Vanity signups.** Registered users are not networks. A signup that arrives without its counterparties is a future churn statistic. Cohort everything by network and by "arrived with connections vs. arrived alone." +- **Launching everywhere shallowly.** Ten cities at 5% density lose to one city at 80%. Anti-network effects run in all ten simultaneously. +- **Demand before supply.** Marketing spend that delivers users into zero states is paying to manufacture detractors. +- **Skipping the bars.** Expanding because the board meeting is Tuesday — rather than because network #1 holds its live bar without founder pedaling — replicates a broken loop at scale. + +## Measuring Tipping: Liquidity Metrics + +Define "live" and "tipped" mechanically, so nobody can argue a network into health: + +| Metric | Definition | Example Bar | +|--------|------------|-------------| +| Fill rate | % of demand requests fulfilled | >80% sustained for 2+ weeks | +| Time-to-match | Median wait from request to match | <10 min for rides; <2 h for services | +| Weekly active networks | Networks above the activity threshold (e.g., a team with 5+ actives) | 60% of launched networks | +| Magic-moment rate | % of new users hitting the magic moment in week one | >40% | +| Zero rate | % of sessions hitting an empty state | <10% and falling | +| Repeat rate | % of users transacting again within 30 days | Rising cohort over cohort | +| Organic share | % of new users arriving via invites and word of mouth | >50% by the tipping point | +| Post-subsidy retention | Activity retention across taper step-downs | No cliff at step-down dates | + +Two practices make these metrics honest. First, report them per network with a live/forming/dead status — averages across networks are where dead launches hide. Second, pair every demand metric with its supply twin (fill rate with utilization, time-to-match with provider idle time) so you can see which side to throttle or subsidize next. + +## The Expansion Checklist + +Before green-lighting network #N+1: + +- [ ] Current cohort holds its live bars for 4+ weeks without founder flintstoning +- [ ] Launch kit updated with what this launch actually cost and which steps mattered +- [ ] Next market selected by scorecard, with explicit adjacency to a tipped network +- [ ] Supply pre-commitment targets signed before any demand spend +- [ ] Subsidy budget approved with a published taper schedule +- [ ] Demand gating plan (waitlist or geofence) in place to protect fill rate +- [ ] Per-network dashboard rows created with the same bars as prior launches +- [ ] A named owner accountable for this market reaching its live bar diff --git a/.agents/skills/contagious/SKILL.md b/.agents/skills/contagious/SKILL.md new file mode 100644 index 00000000..a33b5dd7 --- /dev/null +++ b/.agents/skills/contagious/SKILL.md @@ -0,0 +1,279 @@ +--- +name: contagious +description: 'Engineer word-of-mouth and virality using the STEPPS framework (Social Currency, Triggers, Emotion, Public, Practical Value, Stories). Use when the user mentions "go viral", "word of mouth", "shareable content", "social currency", "why people share", "referral program", "nobody is sharing it", or "make this spread". Also trigger when designing shareable features, crafting social campaigns, or building products that spread through peer recommendation. Covers environmental triggers and high-arousal emotional content. For sticky messaging, see made-to-stick. For persuasion tactics, see influence-psychology.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Word-of-Mouth & Virality Framework + +A framework for engineering word-of-mouth and making products, ideas, and content contagious, based on Jonah Berger's research into why things catch on. Use it to design shareability into products, campaigns, and content instead of hoping for luck. + +## Core Principle + +**Virality is not born — it is engineered.** Products spread because they were designed — consciously or not — to be shared. Only 7% of word-of-mouth happens online; the other 93% happens in offline conversations, so virality is about the psychology of sharing, not social media mechanics. Those psychological patterns are predictable and can be engineered into anything using the STEPPS framework. + +See: [references/word-of-mouth.md](references/word-of-mouth.md) when the brief over-indexes on social media — it makes the offline-vs-online case, lists conversation triggers, and gives a WOM measurement/audit method. + +## Scoring + +**Goal: 10/10.** Score each of the six STEPPS drivers (the six Quick Diagnostic rows) — **0** absent, **1** present but weak, **2** strong and deliberate — for a raw 0-12, then map: 11-12 -> 10, 9-10 -> 8-9, 6-8 -> 6-7, 3-5 -> 4-5, 0-2 -> <=3. Bands: +- **9-10** — three or more drivers at strength 2, at least one of them Public or Social Currency (the self-propagating ones), and the brand survives the Trojan Horse test. +- **6-8** — two drivers genuinely strong, but spread still leans on paid reach or product quality alone. +- **<=5** — at most one weak driver; sharing is incidental, not engineered. + +Report the raw count, the mapped score, and the specific driver(s) to raise next to reach 10/10. + +## STEPPS Overview + +**Not a checklist — a multiplier.** Each principle independently increases sharing; the most contagious ideas activate several at once, but even one or two done well dramatically increase word-of-mouth. + +| Principle | Core Question | Sharing Driver | +|-----------|--------------|----------------| +| **S — Social Currency** | Does sharing it make people look good? | Self-enhancement | +| **T — Triggers** | What in the environment reminds people of it? | Top-of-mind accessibility | +| **E — Emotion** | Does it fire up high-arousal feelings? | Physiological arousal | +| **P — Public** | Can others see people using it? | Observational learning | +| **P — Practical Value** | Is it useful enough to pass along? | Altruism and helpfulness | +| **S — Stories** | Is the brand embedded in a narrative? | Entertainment and identity | + +## The STEPPS Framework + +### 1. Social Currency + +**Core concept:** People share things that make them look good — smart, cool, in-the-know. Make people feel like insiders and they'll spread it to boost their own image. + +**Why it works:** Sharing is self-presentation — listeners infer the sharer's traits from what they pass on, so people curate shares the way they curate clothes. Mechanism: give the sharer a payoff in status or identity and you outsource your marketing to their ego. + +**Key insights:** +- **Remarkability** — surprising, novel, or extreme things make the sharer seem interesting; "Did you know...?" is a powerful sharing trigger +- **Game mechanics** — leaderboards, badges, and status tiers create visible accomplishments people want to display +- **Exclusivity and scarcity** — secret menus and invite-only access give people "insider knowledge" to share +- **Inner remarkability** — even mundane products have a remarkable angle; it's framing, not the product + +**Product applications:** + +| Context | Application | Example | +|---------|------------|---------| +| Content platform | Insider statistics or year-in-review | Spotify Wrapped | +| Mobile app | Shareable accomplishment cards | Duolingo streak badges | +| B2B product | Benchmarking data users want to cite | HubSpot State of Marketing report | + +**Copy patterns:** +- "Most people don't know that..." +- "You're one of the first to try..." +- "You've unlocked [achievement]..." + +**Ethical boundary:** Create real insider value, not false scarcity or manufactured exclusivity that breeds toxicity. + +See: [references/social-currency.md](references/social-currency.md) when a product feels unremarkable — it has the inner-remarkability exercise, game-mechanic design, exclusivity types, and a scored audit. + +### 2. Triggers + +**Core concept:** Top-of-mind means tip-of-tongue. Link your product to environmental cues — sights, sounds, times, routines — so everyday life keeps reminding people to talk about you. + +**Why it works:** Most word-of-mouth is driven not by excitement but by whatever happens to be top-of-mind mid-conversation; a product linked to a frequent cue gets mentioned more because it's more accessible in memory. + +**Key insights:** +- **Frequency beats strength** — a daily trigger (coffee) outperforms a powerful but rare one (a holiday); Kit Kat linked itself to coffee breaks +- **Habitat matters** — map where and when people encounter contexts related to your product +- **Competitive triggers** — link a competitor's moment to your own brand +- **Ongoing vs. temporary** — persistent environmental triggers sustain word-of-mouth; event triggers only spike it + +**Product applications:** + +| Context | Application | Example | +|---------|------------|---------| +| Food/Beverage | Link to a daily habit | Kit Kat + coffee break | +| Productivity tool | Tie to a recurring workflow moment | "Every Monday standup..." | +| Financial product | Link to payday | "Every time you get paid..." | + +**Copy patterns:** +- "Every time you [frequent activity], think of..." +- "Next time you [daily habit]..." +- "It's [day/time] — time for..." + +**Ethical boundary:** Build genuine, helpful associations — hijacking sensitive contexts (grief, health scares) as triggers backfires. + +See: [references/triggers.md](references/triggers.md) when picking a cue to attach to — it has the habitat-analysis worksheet, the frequency matrix, and the 4-step trigger design process. + +### 3. Emotion + +**Core concept:** When we care, we share. High-arousal emotions — positive (awe, excitement, amusement) or negative (anger, anxiety) — drive sharing; low-arousal emotions (sadness, contentment) suppress it. + +**Why it works:** Physiological arousal — racing heart, activated state — creates a need to share. It's activation vs. deactivation, not positivity vs. negativity. + +**Key insights:** +- High-arousal drives sharing: awe, excitement, amusement, inspiration, anger, anxiety +- Low-arousal suppresses it: contentment and relaxation feel no urgency; sadness makes people withdraw +- **Awe is the most powerful sharing emotion** — feeling small before something vast or surprising spreads furthest +- **Emotional framing** — the same facts can be framed for different arousal levels; facts inform, framing motivates sharing + +**Product applications:** + +| Context | Application | Example | +|---------|------------|---------| +| Launch content | Engineer awe through unexpected scale or beauty | Apple keynote reveals | +| Product demos | Amusement through unexpected use | Blendtec "Will It Blend?" | +| Social campaigns | Righteous anger at an injustice | Dove "Real Beauty" challenging beauty standards | + +**Copy patterns:** +- "I can't believe [surprising fact]..." +- "Watch what happens when..." +- "This will change how you think about..." + +**Ethical boundary:** Engineering outrage for clicks corrodes trust — use high-arousal negative emotion sparingly and only when the cause genuinely warrants it. + +See: [references/emotion.md](references/emotion.md) when content feels flat — it has the emotion-sharing matrix, awe-engineering techniques, and humor design rules. + +### 4. Public + +**Core concept:** Built to show, built to grow. If people can see others using your product, they're more likely to adopt it — design for observability. + +**Why it works:** Visible choices resolve uncertainty for the observer — seeing others use a product lowers their perceived risk and supplies social proof at zero marginal cost, so observability turns each user into a passive, continuous billboard. + +**Key insights:** +- **Behavioral residue** — design visible traces that outlast use: a Livestrong wristband long outlives the donation +- **Self-advertising products** — every Hotmail email carried "Get your free email at Hotmail"; the product marketed itself through use +- **Public = imitable** — people can only copy what they can observe; find ways to make invisible usage visible + +**Product applications:** + +| Context | Application | Example | +|---------|------------|---------| +| Email/Messaging | Branded signatures | "Sent from my iPhone" | +| Physical products | Visible branding during use | Apple's outward-facing MacBook logo — every open laptop a billboard | +| SaaS tools | Public outputs crediting the tool | "Powered by [tool]" on customer sites | + +**Copy patterns:** +- "Show the world you [achievement/identity]..." +- "Share your [output] — powered by [brand]..." +- "Join [number] others who..." + +**Ethical boundary:** Visibility must empower, never shame — users always control what becomes public, and private data (failures, health, finances) stays private. + +See: [references/public-visibility.md](references/public-visibility.md) when usage is invisible — it has the public-vs-private breakdown, the behavioral-residue design checklist, and the Apple-logo design lesson. + +### 5. Practical Value + +**Core concept:** People share useful information to help others. News you can use spreads — especially packaged for easy passing along. + +**Why it works:** Sharing practical value is altruism — if your content saves people time, money, or effort, they'll forward it as a favor to their network. + +**Key insights:** +- **Prospect Theory** — people judge deals against reference points: $10 off a $20 item feels better than $10 off a $1,000 item +- **Rule of 100** — under $100, use percentage discounts ("50% off"); over $100, use dollar amounts ("$200 off") +- **Narrow audience = wider sharing** — niche content gets forwarded to "the person who needs this" +- **Knowledge packaging** — lists, how-tos, and tip collections are inherently more shareable than essays + +**Product applications:** + +| Context | Application | Example | +|---------|------------|---------| +| Pricing/Promotions | Frame deals via Rule of 100 | "Save 40%" under $100 vs. "Save $500" over $100 | +| Content marketing | Numbered, forwardable lists | "7 ways to reduce your electricity bill" | +| B2B content | Shareable tools and benchmarks | Free ROI calculator with shareable results | + +**Copy patterns:** +- "The [number]-step guide to..." +- "Quick tip: [immediately useful advice]..." +- "Share this with someone who needs to hear it" + +**Ethical boundary:** Value must be genuine — inflated "original" prices and clickbait life hacks destroy trust faster than they generate shares. + +See: [references/practical-value.md](references/practical-value.md) when framing a deal or packaging tips — it applies Prospect Theory, the Rule of 100 quick reference, and the knowledge-packaging hierarchy. + +### 6. Stories + +**Core concept:** People don't share information — they tell stories. Embed your idea in a narrative people want to retell, and the brand rides along like a Trojan Horse. + +**Why it works:** Humans think in narratives, and absorption in a story lowers critical defenses — the embedded message lands where a direct pitch would bounce. + +**Key insights:** +- **The Trojan Horse test** — if someone can retell the story without your brand, the story fails; the brand must be integral +- **Retellability** — the story must survive casual conversation; a 10-minute setup won't spread +- **Valuable virality** — a hilarious ad nobody attributes to the brand is a failure +- **Narrative transportation** — absorbed listeners accept the embedded message more readily + +**Product applications:** + +| Context | Application | Example | +|---------|------------|---------| +| Brand marketing | Narrative inseparable from product | Blendtec "Will It Blend?" — can't retell without the brand | +| PR/Earned media | Inherently story-worthy stunts | Barclay Prime's $100 cheesesteak | +| Product launch | Origin story around a customer problem | "We built this because our founder couldn't find..." | + +**Copy patterns:** +- "Here's the story of how..." +- "It all started when [founder/customer] realized..." +- "Nobody believed [audacious claim] — until..." + +**Ethical boundary:** Stories must be true or clearly fictional — fabricated testimonials and invented origins eventually surface and poison future word-of-mouth. + +See: [references/stories-trojan-horse.md](references/stories-trojan-horse.md) when shaping the narrative — it has the brand-integration test and four story templates (demo, stunt, origin, customer-hero). + +## Engineering Word of Mouth + +STEPPS principles compound when combined. See: [references/case-studies.md](references/case-studies.md) for end-to-end STEPPS breakdowns (Blendtec, Barclay Prime, Kit Kat, Livestrong, Dove, Hotmail) when you need a worked precedent to model a campaign on. + +### Product Launch + +| Phase | STEPPS Combination | Tactics | +|-------|-------------------|---------| +| Pre-launch | Social Currency + Public | Invite-only beta with visible waitlist | +| Launch day | Emotion + Stories | Founder narrative + awe-inducing demo | +| First week | Triggers + Practical Value | Tie to daily workflow + share-to-unlock features | +| Sustained growth | Public + Social Currency | Visible usage signals + achievement sharing | + +### Content Strategy + +| Content Type | Primary STEPPS | Secondary STEPPS | Example | +|-------------|---------------|-----------------|---------| +| Thought leadership | Social Currency | Stories | Insider knowledge wrapped in narrative | +| How-to guides | Practical Value | Triggers | Tips tied to recurring situations | +| Brand films | Emotion | Stories | Awe-inspiring narrative with brand at center | +| Interactive tools | Practical Value | Public | Calculator/quiz with shareable results | + +See: [references/viral-content-patterns.md](references/viral-content-patterns.md) when choosing a content format — it ranks formats by shareability, gives platform-specific patterns, and defines the viral coefficient. + +### Feature Design + +| Feature Goal | STEPPS to Apply | Implementation | +|-------------|----------------|----------------| +| Drive referrals | Social Currency + Public | Shareable achievement cards with branding | +| Increase retention | Triggers + Practical Value | Daily-routine integrations with useful outputs | +| Build community | Public + Social Currency | Visible membership tiers and contribution badges | +| Launch virally | Emotion + Stories | Remarkable origin story + emotionally charged demo | + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Focusing only on online sharing | 93% of WOM is offline | Design conversation triggers, not just share buttons | +| Shareable but not brand-linked | People share the joke, forget who made it | Apply the Trojan Horse test | +| Using low-arousal emotions | Sadness and contentment don't activate sharing | Reframe for awe, excitement, amusement, or anger | +| Invisible product usage | No one imitates what they can't see | Add behavioral residue and observable signals | +| Relying on product quality alone | Great products without STEPPS spread slowly | Deliberately engineer 2-3 STEPPS into the experience | +| Rare, powerful triggers | Infrequent cues generate less WOM than daily ones | Prioritize trigger frequency over strength | + +## Quick Diagnostic + +| Question | If No... | Action | +|----------|----------|--------| +| Does sharing this make people look good? | No social currency | Add remarkability, exclusivity, or achievements | +| Is there an everyday cue that recalls it? | No trigger | Link to a frequent environment or routine | +| Does it evoke high-arousal emotion? | Low activation | Reframe for awe, excitement, humor, or righteous anger | +| Can others see people using it? | Invisible usage | Add observable signals or branded outputs | +| Is it useful enough to forward? | Low practical value | Package as tips, lists, or tools people would send a friend | +| Is the brand embedded in a retellable story? | No narrative vehicle | Create a Trojan Horse story that needs your brand | + +## Further Reading + +- [Contagious: Why Things Catch On](https://www.amazon.com/Contagious-Things-Catch-Jonah-Berger/dp/1451686579?tag=wondelai00-20) by Jonah Berger +- [The Catalyst: How to Change Anyone's Mind](https://www.amazon.com/Catalyst-How-Change-Anyones-Mind/dp/1982108606?tag=wondelai00-20) by Jonah Berger + +## About the Author + +**Jonah Berger** is a marketing professor at the Wharton School whose research focuses on social influence, word-of-mouth, and why things catch on. *Contagious* distills that research into the STEPPS framework; he also wrote *Invisible Influence* and *The Catalyst* and consults for companies from startups to the Fortune 500. diff --git a/.agents/skills/contagious/references/case-studies.md b/.agents/skills/contagious/references/case-studies.md new file mode 100644 index 00000000..10698b90 --- /dev/null +++ b/.agents/skills/contagious/references/case-studies.md @@ -0,0 +1,290 @@ +# Case Studies: STEPPS Principles in Action + +These detailed case study breakdowns illustrate how the STEPPS framework operates in real-world examples. Each case study analyzes what the company or organization did, which STEPPS principles they activated, why it worked from a psychological perspective, and what lessons are transferable to other products and industries. + +## Case Study 1: Blendtec "Will It Blend?" + +### Background + +Blendtec is a manufacturer of commercial and consumer blenders based in Orem, Utah. In 2006, the company had strong commercial sales (restaurant and food service blenders) but struggled in the consumer market. Their blenders were powerful but expensive, and the brand had virtually zero consumer awareness. + +Marketing director George Wright discovered that founder Tom Dickson had been testing blenders by blending unusual items — wood boards, marbles — to check durability. Wright realized this was not just a quality assurance process. It was a content goldmine. + +### What They Did + +They launched a YouTube series called "Will It Blend?" in which Tom Dickson, wearing a lab coat and safety goggles, would blend increasingly extreme objects: golf balls, a rake handle, glow sticks, and most famously, an iPhone. Each video followed an identical format: Tom introduces the object, asks "Will it blend?", blends it, reveals the result, and delivers his catchphrase: "Don't breathe this." + +The production budget per video was approximately $50-100 — the cost of the blended item. + +### STEPPS Analysis + +| Principle | How It Was Activated | Strength | +|-----------|---------------------|----------| +| **Social Currency** | "Did you see them blend an iPhone?" made sharers seem plugged-in and entertaining | Strong | +| **Triggers** | Each new viral object (iPhone launches, trending products) became a trigger | Moderate | +| **Emotion** | Amusement (high-arousal positive) from the absurdity of blending an iPad | Very Strong | +| **Public** | YouTube views, embeds, and social shares made it highly visible | Strong | +| **Practical Value** | Implicitly demonstrates extreme blending power ("Imagine what it does to food") | Moderate | +| **Stories** | Perfect Trojan Horse — you cannot retell the story without mentioning Blendtec | Very Strong | + +### Why It Worked + +**The Trojan Horse was perfect.** Try to tell someone about this series without mentioning Blendtec or "a blender." You can't. The product IS the story. The humor comes from the blender's power. Remove the blender, and there is no story. + +**It generated awe-adjacent amusement.** Watching a blender destroy an iPhone is funny, but it's also impressive. The combination of humor and amazement (both high-arousal emotions) created a powerful sharing cocktail. + +**It was a series, not a one-off.** The "Will It Blend?" format was infinitely extensible. Each new popular product (iPhone, iPad, Amazon Echo) became a new episode. This created anticipation and a reason to subscribe. + +**The cost-to-impact ratio was extraordinary.** Each video cost less than $100 to produce but generated millions of views and measurable sales lift. + +### Results + +- YouTube channel accumulated hundreds of millions of views +- Consumer sales of Blendtec blenders increased by 700% +- The series ran for over a decade with sustained interest +- Tom Dickson became a recognizable figure, further linking person to brand +- The format was so successful it became a case study in marketing textbooks worldwide + +### Transferable Lessons + +1. **Demonstrate your core product claim in the most extreme way possible.** What is the most outrageous thing your product can do that proves its core value proposition? +2. **Create a repeatable format.** A series builds audience, anticipation, and a content library. One viral video is a spike; a series is a growth engine. +3. **Make the product the protagonist.** The product should not be the sponsor of the entertainment — it should be the source of the entertainment. +4. **Keep production simple.** The authenticity of a simple setup (one man, one blender, one camera) was part of the charm. Overproduction would have undermined the effect. + +## Case Study 2: Barclay Prime's $100 Cheesesteak + +### Background + +Barclay Prime was a new upscale steakhouse opening in Philadelphia in 2004. Philadelphia is one of the most competitive restaurant markets in the US, and the city is especially proud of its cheesesteak — a working-class sandwich typically costing $5-10. Restaurant owner Howard Wein needed to generate buzz for a new, expensive restaurant with no existing reputation. + +### What They Did + +Wein created a $100 cheesesteak. Not a $100 steak — a $100 cheesesteak. It was made with Kobe beef, lobster tail, shaved truffles, and marbled cheese, served with a split of Veuve Clicquot champagne. The sandwich was placed on the menu alongside regular (expensive but not outrageous) offerings. + +### STEPPS Analysis + +| Principle | How It Was Activated | Strength | +|-----------|---------------------|----------| +| **Social Currency** | Ordering or knowing about the $100 cheesesteak signals insider status and adventurousness | Very Strong | +| **Triggers** | Every cheesesteak shop in Philadelphia became a trigger for Barclay Prime | Moderate | +| **Emotion** | Surprise and amusement — the audacity of a $100 cheesesteak in Philly | Strong | +| **Public** | People photographed and displayed the cheesesteak; media covered it extensively | Strong | +| **Practical Value** | Low (it's not a "deal") | Weak | +| **Stories** | "I went to this restaurant that has a $100 cheesesteak" is an irresistible story | Very Strong | + +### Why It Worked + +**Remarkability through extreme contrast.** Philadelphia cheesesteaks cost $5-10. A $100 cheesesteak violates every expectation. The extreme price differential between the norm and the offering creates instant remarkability. It's a "Did you know...?" fact that spreads itself. + +**The Trojan Horse was airtight.** You cannot tell someone about the $100 cheesesteak without mentioning Barclay Prime (or at minimum, the restaurant that serves it, which leads to Barclay Prime). The restaurant IS the story. + +**Social Currency multiplied.** People who ordered it earned extreme social currency — "I had the $100 cheesesteak at Barclay Prime" is a dinner party story that signals adventurousness, affluence, and insider knowledge. But even people who didn't order it gained social currency from knowing about it. + +**Media amplification.** The $100 cheesesteak was covered by every food blogger, local news outlet, and eventually national media. The media earned social currency by covering it (their audiences would find it remarkable), creating a virtuous cycle. + +### Results + +- Barclay Prime became one of the most talked-about restaurants in Philadelphia from opening day +- The $100 cheesesteak generated millions of dollars in free media coverage +- The restaurant's other (regularly priced) menu items benefited from the foot traffic and reputation +- The concept has been copied by restaurants worldwide (the "loss-leader remarkable item" strategy) + +### Transferable Lessons + +1. **You don't need to make your entire product remarkable — just one element.** The rest of Barclay Prime's menu was normally priced. The $100 cheesesteak was a single menu item that generated awareness for the whole restaurant. +2. **Violate category expectations.** Take something people think they know (cheesesteaks are cheap) and subvert it dramatically. +3. **The remarkable item doesn't need to be profitable.** The cheesesteak was likely a break-even or loss-leader item. Its value was in word-of-mouth, not direct margin. +4. **Leverage cultural context.** A $100 cheesesteak in Philadelphia — the cheesesteak capital of the world — was far more remarkable than a $100 cheesesteak in any other city. + +## Case Study 3: Kit Kat + Coffee Breaks + +### Background + +By 2007, Kit Kat was a mature brand with declining sales. The candy bar market is intensely competitive, and Kit Kat needed a way to increase consumption without changing the product itself. + +### What They Did + +Kit Kat repositioned around coffee breaks. The existing tagline "Have a break, have a Kit Kat" was paired systematically with coffee imagery and messaging. Every advertisement, in-store display, and promotional material showed Kit Kat alongside coffee. The association was repeated relentlessly across all channels. + +### STEPPS Analysis + +| Principle | How It Was Activated | Strength | +|-----------|---------------------|----------| +| **Social Currency** | Low — this wasn't about making people look good | Weak | +| **Triggers** | Every coffee break (2-3 times/day for most adults) triggered thoughts of Kit Kat | Very Strong | +| **Emotion** | Moderate — comfort and routine satisfaction | Moderate | +| **Public** | Moderate — seeing someone eating Kit Kat with coffee reinforced the link | Moderate | +| **Practical Value** | Low | Weak | +| **Stories** | Low | Weak | + +### Why It Worked + +**Frequency is everything.** Coffee breaks happen 2-3 times per day for most working adults. By linking Kit Kat to this daily ritual, the brand went from occasional indulgence to top-of-mind multiple times per day. Each coffee break was a trigger. + +**The trigger was already social.** Coffee breaks often involve going to a break room, a coffee shop, or a meeting with colleagues — all social situations where conversation (and therefore word-of-mouth) naturally occurs. The trigger coincided with conversation opportunities. + +**The link was plausible.** "Coffee and chocolate" is a natural pairing. The association didn't feel forced. If Kit Kat had tried to link itself to, say, brushing your teeth, the association would have failed because the pairing feels wrong. + +### Results + +- Kit Kat sales reversed their decline and grew significantly +- The brand solidified its association with coffee breaks in consumer memory +- The strategy has been maintained for years, reinforcing the trigger with each new campaign + +### Transferable Lessons + +1. **Frequency of trigger beats strength of excitement.** A daily, mundane trigger generates more word-of-mouth than an exciting but rare association. +2. **Link to existing behaviors, don't create new ones.** Kit Kat didn't try to create a new ritual. They attached to an existing one (coffee breaks). +3. **Consistency is critical.** The coffee association was maintained for years across all channels. A trigger link takes time to build and must be reinforced continuously. +4. **Choose triggers that coincide with social moments.** A trigger that occurs during conversation is twice as valuable — it reminds people of the product at the exact moment they can mention it. + +## Case Study 4: Livestrong Wristband + +### Background + +In 2004, Nike and the Lance Armstrong Foundation (now the Livestrong Foundation) wanted to raise awareness and funds for cancer research. They needed something that would spread beyond the cycling and cancer communities. + +### What They Did + +They created a simple yellow silicone wristband, sold for $1. The bright yellow color was distinctive, the material was comfortable for all-day wear, and the price was so low that anyone could participate. The initial goal was to sell 5 million bands. + +### STEPPS Analysis + +| Principle | How It Was Activated | Strength | +|-----------|---------------------|----------| +| **Social Currency** | Wearing the band signaled "I care about cancer research" — positive identity signal | Strong | +| **Triggers** | Seeing the yellow band on anyone's wrist triggered awareness | Strong | +| **Emotion** | Inspiration and hope (high-arousal positive) | Strong | +| **Public** | The wristband was visible on the wrist during all daily activities — maximum observability | Very Strong | +| **Practical Value** | Low (no utility beyond signaling) | Weak | +| **Stories** | Lance Armstrong's cancer survival story was integral | Strong | + +### Why It Worked + +**Maximum public visibility.** The wristband was visible all day, every day — at work, at the gym, at meals, in conversation. Unlike a donation receipt (private), the wristband turned a private act (donating) into a public signal (wearing). + +**Behavioral residue that outlasts the act.** The donation took 10 seconds. The wristband was worn for months or years. Each day of wearing was a day of passive advertising. + +**Self-reinforcing visibility loop.** As more people wore the bands, more people noticed them, asked about them, and bought their own. Visibility created demand, which created more visibility. + +**Identity signaling without cost.** For $1, anyone could signal "I care about cancer research." The barrier to entry was essentially zero, which maximized adoption. + +### Results + +- 85 million wristbands sold (17x the original goal) +- Raised $100+ million for cancer research +- Spawned an entire industry of cause-related wristbands (pink for breast cancer, etc.) +- The yellow wristband became a universal symbol of cancer awareness + +### Transferable Lessons + +1. **Design for wearability.** The wristband succeeded because people wore it all day. Design your "visible artifact" for continuous, comfortable display. +2. **Use a distinctive visual signature.** The bright yellow color stood out against any clothing or background. It was identifiable from across a room. +3. **Minimize the barrier to entry.** At $1, the wristband removed all financial friction. More people participating = more visibility = more adoption. +4. **Pair with a powerful story.** The Livestrong wristband was connected to Lance Armstrong's cancer survival narrative, giving the band emotional weight beyond a simple accessory. + +## Case Study 5: Dove "Real Beauty" Campaign + +### Background + +In 2004, Dove (a Unilever brand) was a commodity soap and personal care brand competing on product features in a crowded market. They needed to differentiate beyond ingredients and price. + +### What They Did + +Dove launched the "Campaign for Real Beauty," which featured real women (not models) of various body types, ages, and ethnicities in their advertising. The campaign challenged the beauty industry's narrow definitions of beauty, most powerfully through the "Evolution" video (showing a model's transformation through makeup and Photoshop) and the "Real Beauty Sketches" video (showing women described to a forensic sketch artist by themselves vs. by strangers, revealing how harshly women judge their own appearance). + +### STEPPS Analysis + +| Principle | How It Was Activated | Strength | +|-----------|---------------------|----------| +| **Social Currency** | Sharing the campaign signaled progressive values and empathy | Strong | +| **Triggers** | Every beauty ad (from competitors) became a trigger for Dove's counter-message | Moderate | +| **Emotion** | Complex high-arousal blend: anger (at beauty standards), inspiration (real beauty), awe (the sketch reveal) | Very Strong | +| **Public** | Massive media coverage, social sharing, billboards, in-store displays | Strong | +| **Practical Value** | Moderate — provided an empowering perspective on self-image | Moderate | +| **Stories** | The individual women's stories were deeply human and retellable | Very Strong | + +### Why It Worked + +**Multiple high-arousal emotions simultaneously.** The campaign triggered anger (at unrealistic beauty standards), inspiration (seeing real women celebrated), surprise (the sketch reveal was genuinely shocking), and awe (the emotional power of the realization). This emotional cocktail was extremely high-arousal. + +**The story carried the brand.** "Dove did a campaign showing real women instead of models" is a story you can tell in one sentence that carries the brand name. The Trojan Horse worked because Dove's brand was integral to the narrative of challenging beauty norms. + +**Competitor advertising became a trigger.** Every time someone saw a traditional beauty ad with airbrushed models, it triggered thoughts of Dove's counter-message. Competitors' own advertising inadvertently promoted Dove's positioning. + +**Identity signaling through sharing.** Sharing the Dove campaign signaled "I believe in real beauty" and "I reject unrealistic standards" — both positive identity signals. This social currency drove massive sharing across demographics. + +### Results + +- "Real Beauty Sketches" became the most-watched ad of all time with 180+ million views +- Dove's sales increased from $2.5 billion to $4 billion in the campaign's first decade +- The campaign has run for 20+ years, continuously evolving +- Spawned industry-wide conversation about beauty standards in advertising + +### Transferable Lessons + +1. **Challenge industry norms that people already resent.** The backlash against unrealistic beauty standards was simmering. Dove gave it voice and a brand to rally around. +2. **Turn competitor behavior into your trigger.** When competitors do the thing you challenge, they inadvertently promote your message. +3. **Multi-emotion activation amplifies sharing.** The campaign didn't just make people feel one thing — it made them feel many things intensely. +4. **Take a stand.** Commodity products differentiate through values, not features. Dove sold soap by standing for something bigger than soap. + +## Case Study 6: Hotmail "Get Your Free Email" + +### Background + +In 1996, Hotmail was one of the first free web-based email services. Founders Sabeer Bhatia and Jack Smith needed to grow the user base rapidly with virtually no marketing budget. + +### What They Did + +They added a simple line at the bottom of every email sent by a Hotmail user: "Get your free email at Hotmail" with a clickable link. Every email sent from a Hotmail account became an advertisement for Hotmail delivered to a non-user. + +### STEPPS Analysis + +| Principle | How It Was Activated | Strength | +|-----------|---------------------|----------| +| **Social Currency** | Early on, having free web-based email was novel and tech-savvy | Moderate | +| **Triggers** | Every email from a Hotmail user was a trigger | Very Strong | +| **Emotion** | Low — functional, not emotional | Weak | +| **Public** | Every email was a public display of Hotmail usage — self-advertising product | Very Strong | +| **Practical Value** | Free email (previously paid) was genuinely valuable | Strong | +| **Stories** | Low | Weak | + +### Why It Worked + +**The product advertised itself through normal use.** This is the purest form of the Public principle. Hotmail users didn't have to do anything special to promote the product. Just by using email normally, they exposed every recipient to the Hotmail brand and offer. + +**Implicit endorsement.** When you receive an email from a friend who uses Hotmail, the friend is implicitly endorsing the product. They chose it and use it. This carried more weight than any advertisement. + +**Practical value was clear.** "Free email" in 1996 — when most email required a paid ISP — was immediately, obviously valuable. The value proposition was self-evident. + +**Network effects.** As more people joined Hotmail, more emails carried the tagline, exposing more non-users, who then joined and sent more emails. This was a textbook viral loop. + +### Results + +- Hotmail grew from 0 to 12 million users in 18 months +- Was acquired by Microsoft for $400 million in 1997 +- The self-advertising email signature became a template copied by countless companies +- "Sent from my iPhone" is a direct descendant of this strategy + +### Transferable Lessons + +1. **Make your product self-advertising.** If your product produces output that others see, brand that output. +2. **Make the advertising default, not opt-in.** Users had to actively remove the Hotmail signature. Most didn't bother. Default = maximum exposure. +3. **Embed the value proposition in the advertisement.** "Get your free email" is simultaneously a brand exposure and a clear value proposition. The ad does double duty. +4. **Every user touchpoint with a non-user is a marketing opportunity.** Identify every moment your product touches someone who isn't a user, and make sure it includes a brand signal and value proposition. + +## Cross-Case Analysis: What the Best Cases Have in Common + +| Pattern | Blendtec | Barclay Prime | Kit Kat | Livestrong | Dove | Hotmail | +|---------|----------|--------------|---------|-----------|------|---------| +| Product IS the story | Yes | Yes | No | Partially | Yes | No | +| Activates 3+ STEPPS | Yes | Yes | No (mainly Triggers) | Yes | Yes | Yes | +| Low-cost to execute | Yes | Yes | No (major ad spend) | Yes ($1 product) | No (major campaign) | Yes (free) | +| Creates a series/ongoing | Yes | No (single item) | Yes (ongoing campaign) | No (single product) | Yes (ongoing campaign) | Yes (every email) | +| Brand integral to retelling | Yes | Yes | Yes | Yes | Yes | Yes | +| Self-reinforcing loop | Yes (more views = more shares) | Yes (more buzz = more diners = more stories) | Yes (more coffee = more Kit Kat thoughts) | Yes (more wristbands = more visibility = more sales) | Yes (more sharing = more awareness = more sales) | Yes (more users = more emails = more users) | + +### The Universal Lesson + +Every successful case shares one fundamental trait: **the brand cannot be separated from the sharing mechanism.** Whether it's a Trojan Horse story (Blendtec, Barclay Prime), a public signal (Livestrong, Hotmail), a trigger link (Kit Kat), or a values stand (Dove), the brand is structurally embedded in the thing that spreads. This is the difference between content that builds brand and content that just entertains. diff --git a/.agents/skills/contagious/references/emotion.md b/.agents/skills/contagious/references/emotion.md new file mode 100644 index 00000000..2932e87e --- /dev/null +++ b/.agents/skills/contagious/references/emotion.md @@ -0,0 +1,207 @@ +# Emotion: Engineering High-Arousal Feelings That Drive Sharing + +When we care, we share. But not all emotions are created equal. High-arousal emotions — both positive and negative — drive sharing, while low-arousal emotions suppress it. The difference between content that spreads and content that dies is not whether it makes people feel good or bad, but whether it fires them up or brings them down. + +## The Arousal Framework + +The critical distinction is not positive vs. negative, but high-arousal vs. low-arousal. Arousal is a state of physiological activation — elevated heart rate, tightened muscles, a sense of readiness for action. High-arousal states create a need to share, talk, and act. Low-arousal states create withdrawal, passivity, and silence. + +### The Emotion-Sharing Matrix + +| | **High Arousal (Drives Sharing)** | **Low Arousal (Suppresses Sharing)** | +|---|---|---| +| **Positive** | Awe, Excitement, Amusement, Humor, Inspiration, Surprise | Contentment, Relaxation, Satisfaction, Calm, Serenity | +| **Negative** | Anger, Anxiety, Outrage, Fear, Disgust, Frustration | Sadness, Melancholy, Disappointment, Grief, Boredom | + +### Why This Matrix Matters + +Most marketers think of emotion as a simple positive/negative spectrum. They assume positive = shareable and negative = avoid. This is wrong. + +**Counter-intuitive truths:** +- Sad content (positive intent, like charity ads) often fails to spread because sadness is low-arousal — people feel deflated and withdrawn, not activated +- Angry content (negative valence) often spreads widely because anger is high-arousal — people feel fired up and compelled to act +- Content that makes people feel content and satisfied generates almost no sharing — there's no urgency to act +- Awe-inspiring content is the single most shared type because awe is both positive and extremely high-arousal + +### Detailed Emotion Profiles + +| Emotion | Arousal Level | Valence | Sharing Impact | Example Content | +|---------|--------------|---------|---------------|-----------------| +| **Awe** | Very high | Positive | Very high sharing | "This time-lapse of Earth from space..." | +| **Excitement** | High | Positive | High sharing | Product launch reveals, surprise announcements | +| **Amusement** | High | Positive | High sharing | Clever humor, unexpected twists | +| **Inspiration** | High | Positive | High sharing | Human triumph stories, against-all-odds narratives | +| **Anger** | Very high | Negative | Very high sharing | Injustice revealed, unfair treatment exposed | +| **Anxiety** | High | Negative | High sharing | Urgent threats, time-sensitive warnings | +| **Surprise** | High | Varies | High sharing | Unexpected facts, plot twists, reveals | +| **Contentment** | Low | Positive | Low sharing | Peaceful imagery, status quo confirmation | +| **Sadness** | Low | Negative | Very low sharing | Loss stories, tragedy without resolution | +| **Boredom** | Very low | Negative | No sharing | Predictable, routine information | + +## Awe Engineering + +Awe is the most powerful sharing emotion. It is the feeling of being in the presence of something vast that transcends your current frame of reference. Awe makes people feel small in the best way — connected to something larger than themselves — and that feeling is so powerful they need to share it. + +### What Triggers Awe + +| Awe Trigger | Description | Example | +|------------|-------------|---------| +| **Physical vastness** | Enormous scale, panoramic views | Grand Canyon, space imagery, aerial footage | +| **Intellectual vastness** | Mind-expanding ideas, paradigm shifts | "What if everything you knew about X was wrong?" | +| **Talent/Skill** | Extraordinary human ability | Susan Boyle's Britain's Got Talent audition | +| **Beauty** | Profound aesthetic experience | Time-lapse nature films, architectural marvels | +| **Virtue** | Extraordinary moral acts | Strangers helping strangers, self-sacrifice | +| **Supernatural/Unexplained** | Things that defy understanding | Optical illusions, magic tricks, scientific mysteries | + +### Awe Engineering Techniques + +**Technique 1: Scale Revelation.** Start with something familiar and zoom out (or in) to reveal an unexpected scale. "This is a single cell. This is what it looks like magnified 10,000 times..." + +**Technique 2: The Unexpected Expert.** Present someone who defies expectations and then delivers extraordinary performance. Susan Boyle looked unassuming; her voice was astonishing. The contrast amplifies awe. + +**Technique 3: The Vast Implication.** Take a small fact and show its enormous implications. "Every 60 seconds, [X] happens. That means by the time you finish reading this..." + +**Technique 4: Time Compression/Expansion.** Show slow processes sped up (time-lapse of a city being built) or fast processes slowed down (slow-motion hummingbird flight). Altered time perception triggers awe. + +**Technique 5: The Human Achievement.** Showcase what a single person (or small team) accomplished against impossible odds. "She built this entire bridge by hand over 20 years." + +### Awe Content Checklist + +- [ ] Does the content reveal something vastly larger or more complex than expected? +- [ ] Is there a moment of "I had no idea..." or "How is that possible?" +- [ ] Does it make the viewer feel connected to something bigger than themselves? +- [ ] Is the awe genuine (not manufactured or exaggerated)? +- [ ] Does the awe resolve positively (leaving people inspired, not paralyzed)? + +## Humor Design Principles + +Humor is a high-arousal positive emotion and a powerful sharing driver. But humor is also risky — failed humor is worse than no humor. Here are principles for designing humor that works. + +### Types of Humor That Drive Sharing + +| Humor Type | Mechanism | Best For | Risk Level | +|-----------|-----------|----------|-----------| +| **Incongruity** | Unexpected pairing or twist | Product demos, ads | Low | +| **Superiority** | Feeling smarter than someone/something | Memes, competitive positioning | Medium | +| **Relief** | Breaking tension in a stressful topic | Finance, health, B2B | Low | +| **Self-deprecation** | Brand laughing at itself | Building authenticity | Medium | +| **Absurdity** | Escalating illogic | Viral content, brand personality | High | +| **Observational** | "So true" recognition humor | Social media content, email campaigns | Low | + +### Humor Design Rules + +**Rule 1: The humor must serve the message.** If people laugh but can't remember the product, the humor failed. The funny element should be inseparable from the product benefit. Blendtec's "Will It Blend?" is funny *because* of the blender's power — the humor and the product claim are one. + +**Rule 2: Punch up, not down.** Humor at the expense of vulnerable groups generates backlash, not shares. Punch up at powerful targets (big competitors, universal frustrations, absurd industry norms). + +**Rule 3: Test ruthlessly.** Humor is subjective. What's hilarious to your team may fall flat with your audience. Test with small groups before scaling. + +**Rule 4: Keep it simple.** The best viral humor can be understood in seconds and retold in one sentence. "They blended an iPhone" is a one-sentence joke that carries the entire brand message. + +**Rule 5: Build a series, not a one-off.** A single funny piece is a moment. A series (like "Will It Blend?") builds anticipation, recognition, and a catalog of shareable content. + +### Humor Integration Framework + +| Product Context | Humor Approach | Example | +|----------------|---------------|---------| +| Boring industry | Relief humor — make the mundane funny | Dollar Shave Club "Our blades are f***ing great" | +| Technical product | Absurdity — show extreme use cases | Blendtec blending everything imaginable | +| Premium brand | Self-deprecation — show you don't take yourself too seriously | Luxury brands poking fun at their own exclusivity | +| Commodity product | Observational — "we all know this is true" | Old Spice absurdist takes on deodorant marketing | + +## Emotional Framing + +The same information can be presented in ways that evoke different emotions — and therefore different sharing behaviors. Emotional framing is the art of choosing which emotion to activate. + +### Framing the Same Story + +**The fact:** "A company donated $1 million to clean water initiatives." + +| Frame | Emotion Evoked | Arousal | Shareability | +|-------|---------------|---------|-------------| +| "Clean water is still unavailable to 2 billion people" | Sadness | Low | Low | +| "One company just proved that $1M can bring water to 500,000 people" | Awe/Inspiration | High | High | +| "While big corporations spent millions on Super Bowl ads, this company spent it on saving lives" | Anger at others / Admiration | High | Very High | +| "Watch what happened when a village got clean water for the first time" | Awe / Joy | High | Very High | +| "Clean water access improved slightly in developing regions" | Contentment | Low | Very Low | + +**The lesson:** The facts don't change. The emotion changes based on framing. Always choose the high-arousal frame. + +### Emotional Reframing Techniques + +| Technique | How It Works | Before (Low Arousal) | After (High Arousal) | +|-----------|-------------|---------------------|---------------------| +| **Personalize** | Make it about one person, not statistics | "Millions are affected" | "Meet Sarah, who..." | +| **Contrast** | Show the gap between expectation and reality | "Things are getting better" | "We think X is true, but actually..." | +| **Urgency** | Add time pressure | "This is a problem" | "In the next 60 seconds, [Y] will happen" | +| **Empower** | Show what the audience can do | "This is happening" | "Here's what you can do about it right now" | +| **Scale revelation** | Make abstract numbers concrete | "50 million tons of waste" | "That's enough to fill [landmark] 10 times" | + +## The Emotional Audit + +Use this audit to evaluate the emotional impact of any content, campaign, or product experience. + +### Step 1: Identify the Dominant Emotion + +Watch, read, or experience the content. What emotion do you feel most strongly? Name it specifically (not just "positive" or "negative"). + +### Step 2: Map It on the Arousal Spectrum + +| Your Dominant Emotion | Arousal Level | Sharing Prediction | +|----------------------|---------------|-------------------| +| Awe, amazement | Very high | Will be shared widely | +| Excitement, anticipation | High | Will be shared with enthusiasm | +| Amusement, humor | High | Will be shared for social bonding | +| Anger, outrage | Very high | Will be shared with urgency | +| Anxiety, concern | High | Will be shared as warning | +| Surprise | High | Will be shared as "Did you see this?" | +| Contentment | Low | Will not be shared — no urgency | +| Sadness | Low | Will not be shared — people withdraw | +| Indifference | None | Dead on arrival | + +### Step 3: If Low Arousal, Reframe + +If your content evokes low-arousal emotions, apply the reframing techniques above. Find the high-arousal angle without changing the core message. + +### Step 4: Verify Brand Integration + +High arousal alone is not enough. The emotion must be connected to your brand or product. Ask: "Would removing the brand from this content change the emotional experience?" If no, the emotion is generic and won't drive brand-specific word-of-mouth. + +## Testing Emotional Arousal + +### Quick Test Methods + +| Method | How It Works | What to Measure | +|--------|-------------|-----------------| +| **Physiological proxy** | Ask testers to squeeze a handgrip while consuming content. High-arousal content produces stronger grip | Grip strength correlates with arousal | +| **Share intent** | After consuming content, ask: "Would you share this? With whom? Right now?" | Immediacy of intent = arousal indicator | +| **Physical response observation** | Watch for leaning forward, widened eyes, verbal exclamations | Physical activation = high arousal | +| **The "pause" test** | Does the person pause what they're doing to fully engage? | Interruption of routine = strong arousal | +| **The "retell" test** | Within 5 minutes, does the person tell someone else about it? | Spontaneous sharing = high arousal confirmed | + +### A/B Testing Emotional Frames + +| Test Variable | Version A | Version B | Metric | +|--------------|-----------|-----------|--------| +| Headline emotion | Informational (low arousal) | Awe-inducing (high arousal) | Share rate | +| Opening frame | Statistics-led | Story-led | Watch time + shares | +| CTA emotion | Rational ("Learn more") | Urgent ("Don't miss this") | Click-through + forwards | +| Visual tone | Calm, professional | Dynamic, surprising | Engagement + sharing | + +## Exercises + +### Exercise 1: Emotion Mapping + +Take your last 10 pieces of content (emails, posts, ads, features). For each, identify the dominant emotion and rate its arousal level. How many fall in the high-arousal zone? Reframe the low-arousal pieces. + +### Exercise 2: Awe Inventory + +List 5 things about your product, industry, or customer results that are genuinely awe-inspiring. For each, design a content piece that reveals the awe through one of the engineering techniques above. + +### Exercise 3: The Reframe Challenge + +Take one piece of content that performs poorly. Identify its emotional frame. Rewrite it in three different high-arousal frames (awe, humor, anger). Test all three and compare sharing rates. + +### Exercise 4: Arousal Calibration + +Gather 5 people. Show them 10 pieces of content (mixed arousal levels). For each, ask them to rate (1-10): "How activated do you feel?" and "Would you share this right now?" Plot the correlation. Use this calibration to predict future content performance. diff --git a/.agents/skills/contagious/references/practical-value.md b/.agents/skills/contagious/references/practical-value.md new file mode 100644 index 00000000..a631538e --- /dev/null +++ b/.agents/skills/contagious/references/practical-value.md @@ -0,0 +1,222 @@ +# Practical Value: Making Information Worth Sharing + +People share useful information to help others. If your product, content, or message saves people time, money, health, or effort, they will pass it along as a favor to the people they care about. Practical value is the altruistic engine of word-of-mouth — people share not to make themselves look good, but to help their friends and family. + +## Why Practical Value Drives Sharing + +Unlike Social Currency (which is about self-enhancement), Practical Value is driven by genuine altruism. People forward useful articles, share money-saving tips, and recommend helpful tools because they want to help the people in their network. + +**The key insight:** Practical value content doesn't need to be exciting or remarkable. It just needs to be genuinely useful. A 65-year-old forwarding an article about "10 Ways to Reduce Your Electricity Bill" to their adult children isn't trying to look cool — they're trying to be helpful. This makes Practical Value the most democratic STEPPS principle. Anyone can share something useful. + +**The paradox of narrowness:** Counterintuitively, content targeting a narrow audience often spreads more than broadly targeted content. Why? Because when something is specifically useful to a certain type of person, people actively forward it to "the person who needs this." "You're into gardening — you need to see this" is a more powerful sharing mechanism than "Everyone might find this interesting." + +## Prospect Theory: The Psychology of Value Perception + +Daniel Kahneman and Amos Tversky's Prospect Theory explains how people perceive gains and losses — and it has direct implications for how you frame deals, discounts, and practical value. + +### Core Principles of Prospect Theory + +**Principle 1: Reference Point Dependence.** People evaluate outcomes relative to a reference point, not in absolute terms. A $10 discount feels different depending on the context. + +| Scenario | Absolute Savings | Perceived Value | Why | +|----------|-----------------|----------------|-----| +| $10 off a $20 item | $10 | Feels huge | 50% of the price saved | +| $10 off a $1,000 item | $10 | Feels trivial | 1% of the price saved | +| $10 off a $10 item | $10 | Feels incredible | It's free! | +| $10 off a $50 item | $10 | Feels good | 20% savings | + +**The lesson:** Frame discounts relative to the smallest meaningful reference point. "Save $10 on your $20 purchase" beats "Save $10 on your $200 order." + +**Principle 2: Loss Aversion.** Losses feel roughly twice as painful as equivalent gains feel good. Losing $100 hurts more than finding $100 feels good. + +| Framing | Approach | Example | Perceived Impact | +|---------|----------|---------|-----------------| +| **Gain frame** | "Save $50" | "Get $50 off your next order" | Good | +| **Loss frame** | "Don't lose $50" | "You're leaving $50 on the table" | Stronger | +| **Endowment + loss** | "It's yours, don't lose it" | "Your $50 credit expires tomorrow" | Strongest | + +**The lesson:** Frame practical value in terms of what people will lose by not acting, not just what they'll gain by acting. + +**Principle 3: Diminishing Sensitivity.** The difference between $5 and $10 feels larger than the difference between $495 and $500, even though both differences are $5. Sensitivity to changes diminishes as the base amount increases. + +**The lesson:** Small savings feel bigger when presented against a small reference point. If you can break a large purchase into smaller components, savings on each component feel more significant. + +### Applying Prospect Theory to Content and Products + +| Prospect Theory Principle | Content/Product Application | Example | +|--------------------------|---------------------------|---------| +| Reference point dependence | Frame value against smallest relevant reference | "That's less than your daily coffee" instead of "That's $4.50/day" | +| Loss aversion | Lead with what people lose by not acting | "You're losing $200/month by not..." | +| Diminishing sensitivity | Break large values into per-unit costs | "$1 per meal" instead of "$365/year" | +| Endowment effect | Give something first, then threaten removal | Free trial that expires, credits that vanish | + +## The Rule of 100 + +The Rule of 100 is a practical heuristic for choosing between percentage and absolute discount framing. + +### The Rule + +- **For products under $100:** Use percentage discounts. "50% off" sounds better than "$15 off" on a $30 item. +- **For products over $100:** Use dollar-amount discounts. "$200 off" sounds better than "10% off" on a $2,000 item. + +### Why It Works + +People evaluate the number itself, not just what it represents. A bigger number feels like a bigger deal. + +| Product Price | Percentage Frame | Dollar Frame | Which Sounds Bigger? | Winner | +|--------------|-----------------|-------------|---------------------|--------| +| $30 | 50% off ($15) | $15 off | "50% off" = bigger number | Percentage | +| $50 | 30% off ($15) | $15 off | "30% off" = bigger number | Percentage | +| $80 | 25% off ($20) | $20 off | "25% off" = bigger number | Percentage | +| $150 | 20% off ($30) | $30 off | "$30 off" = bigger number | Dollar | +| $500 | 10% off ($50) | $50 off | "$50 off" = bigger number | Dollar | +| $2,000 | 10% off ($200) | $200 off | "$200 off" = much bigger number | Dollar | + +### Rule of 100 Quick Reference + +| If Price Is... | Use This Frame | Because... | +|----------------|---------------|-----------| +| Under $100 | Percentage (% off) | The percentage number will be larger than the dollar number | +| Exactly $100 | Either (they're equal) | 10% off = $10 off (same number) | +| Over $100 | Dollar amount ($ off) | The dollar number will be larger than the percentage number | + +### Applying the Rule of 100 Beyond Discounts + +The Rule of 100 applies to any quantified value, not just discounts: + +| Context | Under 100 (Use %) | Over 100 (Use Absolute) | +|---------|-------------------|------------------------| +| Speed improvement | "40% faster loading" | "Saves 3 hours per week" | +| Growth metrics | "25% more leads" | "500 additional leads per month" | +| Efficiency gains | "60% less manual work" | "Eliminates 200 hours of manual work" | +| Cost savings | "35% lower costs" | "Save $10,000 annually" | + +## Knowledge Packaging: Making Useful Information Shareable + +Having useful information is necessary but not sufficient. The information must be packaged in a format that is easy to consume, easy to remember, and easy to share. + +### The Knowledge Packaging Hierarchy + +Formats ranked by shareability (most shareable to least): + +| Rank | Format | Why It's Shareable | Best For | +|------|--------|-------------------|----------| +| 1 | **Numbered lists** | Scannable, specific promise ("7 ways to..."), completeness | Tips, strategies, resources | +| 2 | **Infographics** | Visual, self-contained, platform-ready | Data, processes, comparisons | +| 3 | **How-to guides** | Immediately actionable, step-by-step | Tutorials, procedures | +| 4 | **Checklists** | Usable as-is, saves time creating own | Audits, quality checks, planning | +| 5 | **Calculators/tools** | Interactive, personalized output | ROI, savings, planning | +| 6 | **Comparison tables** | Quick decision-making | Product selection, evaluations | +| 7 | **Case studies** | Proof + methodology | B2B, complex products | +| 8 | **Long-form essays** | Deep understanding | Thought leadership | + +### Why Numbered Lists Dominate + +Lists are the most shared content format for several reasons: + +1. **The number sets expectations.** "7 ways to..." tells you exactly what you'll get and how much time it'll take. +2. **Lists are scannable.** Even if you don't read the whole thing, you can get value from scanning. +3. **Lists feel complete.** "All the ways to..." satisfies the completeness need. +4. **Lists are easy to reference.** "Check out tip #3" is easier to share than "Read the paragraph about..." +5. **Lists have built-in structure.** Each item is a mini-unit of value. + +### Designing High-Share Knowledge Content + +**Step 1: Start with the audience need.** What specific problem does your target audience face regularly? "How do I save money on groceries?" is specific. "How do I live better?" is too vague. + +**Step 2: Choose the right format.** Match the format to the content type: + +| Content Type | Best Format | Example | +|-------------|------------|---------| +| Multiple tips on one topic | Numbered list | "9 Ways to Reduce Your Energy Bill" | +| Step-by-step process | How-to guide | "How to Set Up Your Home Office in 30 Minutes" | +| Data or statistics | Infographic | "The State of Remote Work in 2024" | +| Decision support | Comparison table | "Renting vs. Buying: A Side-by-Side Comparison" | +| Personalized output | Calculator/tool | "How Much Are You Spending on Subscriptions?" | +| Quality assurance | Checklist | "The Pre-Launch Checklist for Your Online Store" | + +**Step 3: Optimize the title.** The title should communicate the specific value. Use this formula: + +``` +[Number] + [Adjective] + [Keyword] + [Promise of Value] +``` + +Examples: +- "7 Simple Changes That Cut Our Electricity Bill in Half" +- "The 5-Minute Morning Routine Backed by Neuroscience" +- "3 Free Tools That Replace $500/Month in Software" + +**Step 4: Front-load the value.** Put the most useful information first. Many people share after reading just the headline and first few points. Don't bury the best tip at #7. + +**Step 5: Include a clear "who to share with" trigger.** Either explicitly ("Share this with someone who...") or implicitly by making the target audience so specific that readers naturally think of the right person to forward it to. + +## Making Deals Feel Like Deals + +Even genuinely good deals need to feel like deals. Perception of value often matters more than actual value. + +### Deal Perception Levers + +| Lever | How It Works | Example | +|-------|-------------|---------| +| **Anchor price** | Show the original price prominently | ~~$99~~ Now $49 | +| **Limited time** | Create urgency with a deadline | "Offer expires Friday" | +| **Limited quantity** | Create scarcity | "Only 12 left at this price" | +| **Unexpected discount** | Surprise with savings they didn't expect | "We noticed you were looking at this — here's 20% off" | +| **Stacking** | Show multiple savings combined | "30% off + free shipping + bonus gift" | +| **Per-unit breakdown** | Make cost feel trivial | "Less than $1 per day" | +| **Comparison frame** | Compare to more expensive alternative | "Half the cost of [competitor]" | + +### Making Discounts Shareable + +A deal that's good enough to share follows this pattern: + +1. **It feels exceptional** — not just good, but surprisingly good +2. **It's easy to communicate** — "50% off everything" is shareable; "Up to 50% off select items from participating categories" is not +3. **It's time-bound** — urgency makes people share faster ("Tell your friends before Friday!") +4. **It helps a specific person** — "Your sister who loves cooking would love this" + +### Deal Framing Checklist + +- [ ] Is the original price clearly visible as an anchor? +- [ ] Are you using the Rule of 100 correctly (% for under $100, $ for over)? +- [ ] Is there a deadline or scarcity element creating urgency? +- [ ] Is the deal simple enough to explain in one sentence? +- [ ] Would someone forward this deal to a specific person they know? +- [ ] Does the deal feel exceptional compared to typical offers? + +## Practical Value Audit + +Evaluate any content or offer for practical value sharing potential. + +| Dimension | Question | Score (0-10) | +|-----------|----------|-------------| +| **Usefulness** | Does this genuinely save time, money, or effort? | | +| **Specificity** | Is it targeted to a specific need or audience? | | +| **Actionability** | Can someone act on this immediately? | | +| **Packaging** | Is it in a shareable format (list, tool, infographic)? | | +| **Forwardability** | Would someone send this to a specific person? | | +| **Framing** | Is the value framed using Prospect Theory principles? | | + +**Scoring:** +- **0-20:** Low practical value. Content informs but doesn't compel sharing. +- **21-40:** Moderate practical value. Occasional shares to close contacts. +- **41-50:** High practical value. Regular forwards and saves. +- **51-60:** Exceptional practical value. Widely shared as a "must-read" resource. + +## Exercises + +### Exercise 1: The Rule of 100 Audit + +List your current pricing/discount offers. For each, check whether you're using the Rule of 100 correctly. Reframe any misaligned offers. A/B test the original vs. reframed versions and measure sharing and conversion. + +### Exercise 2: Knowledge Packaging Redesign + +Take your best-performing long-form content. Repackage it as a numbered list, a checklist, and an infographic. Publish all three and compare sharing rates. Which format generates the most forwards and saves? + +### Exercise 3: The Forward Test + +For your next piece of content, before publishing, show it to 5 people and ask: "Would you forward this to someone? Who specifically?" If they can name a specific person, your practical value is strong. If they say "maybe" or "I guess anyone," it's too vague. + +### Exercise 4: Deal Perception Audit + +Take your current best offer. Apply all seven deal perception levers. Create an improved version that feels like a dramatically better deal (even if the actual value hasn't changed). Test both versions and measure sharing rate and conversion. diff --git a/.agents/skills/contagious/references/public-visibility.md b/.agents/skills/contagious/references/public-visibility.md new file mode 100644 index 00000000..11f6bb1b --- /dev/null +++ b/.agents/skills/contagious/references/public-visibility.md @@ -0,0 +1,249 @@ +# Public Visibility: Making the Private Public + +If something is built to show, it's built to grow. People imitate what they can observe. If your product's usage is invisible, you lose the most powerful organic growth channel: social proof through observation. The principle of Public is about designing products, behaviors, and experiences so that using them is inherently visible to others. + +## The Core Principle: Observable = Imitable + +Humans are social learners. We look to others to figure out what to do, what to buy, what to value. But we can only imitate what we can see. This creates a simple but powerful rule: + +**If people can see others using your product, adoption spreads. If they can't, it doesn't.** + +This is why some excellent products grow slowly (invisible usage) while some mediocre products grow fast (highly visible usage). Visibility is not about quality — it's about observability. + +### Public vs. Private Behaviors + +| Behavior Type | Visibility | Word-of-Mouth Impact | Example | +|--------------|-----------|---------------------|---------| +| **Public consumption** | Others can see you using it | High — passive advertising | Wearing Nike shoes, driving a Tesla | +| **Semi-public** | Visible in certain contexts | Medium — context-dependent exposure | Using Slack at work, reading a Kindle | +| **Private consumption** | Others cannot see you using it | Low — requires active sharing | Using a meditation app, taking supplements | +| **Stigmatized private** | Actively hidden from others | Very low — people avoid discussion | Mental health apps, debt management tools | + +**The design challenge:** For private-consumption products, find ways to create public signals without violating privacy. + +## Behavioral Residue: Traces That Outlast the Act + +Behavioral residue is the physical or digital evidence that remains after someone engages with your product. It's the lasting, visible trace that continues to advertise long after the initial use. + +### What Is Behavioral Residue? + +The behavior itself is temporary — you attend a rally, you visit a store, you use an app. But behavioral residue persists: the bumper sticker stays on the car, the tote bag gets carried to the grocery store, the "Powered by" badge stays on the website. + +**Key insight:** The residue often generates more word-of-mouth than the behavior itself, because the residue is visible for much longer. + +### Types of Behavioral Residue + +| Residue Type | Duration | Visibility | Example | +|-------------|----------|-----------|---------| +| **Physical artifacts** | Months to years | High in daily life | Livestrong wristband, conference t-shirt, branded tote bag | +| **Digital artifacts** | Permanent | High online | "Sent from my iPhone," GitHub contribution graph | +| **Environmental marks** | Variable | High in specific contexts | Bumper stickers, yard signs, window decals | +| **Social artifacts** | Variable | Medium | Profile badges, LinkedIn certifications | +| **Output branding** | Per-use | High per interaction | "Made with Canva," "Powered by Shopify" | + +### Designing for Behavioral Residue + +**Principle 1: Make the residue attractive.** People only display residue they're proud of. An ugly bumper sticker gets peeled off. A beautiful tote bag gets used daily. Invest in making residue that people *want* to show. + +**Principle 2: Make the residue useful.** A branded tote bag serves a function (carrying things). A "Sent from my iPhone" signature serves a function (excusing typos). Useful residue gets more display time. + +**Principle 3: Make the residue durable.** Stickers that peel, wristbands that break, and t-shirts that shrink after one wash reduce residue lifetime. Invest in quality. + +**Principle 4: Make the residue voluntary but default.** The best residue is opt-out, not opt-in. "Sent from my iPhone" was a default signature. Most people left it on, not because they wanted to advertise Apple, but because removing it required effort. + +### Behavioral Residue Design Checklist + +- [ ] After someone uses your product, what visible trace remains? +- [ ] Is the trace attractive enough that people would choose to display it? +- [ ] Does the trace serve a practical function beyond branding? +- [ ] Is the trace durable (lasts weeks, months, or years)? +- [ ] Is the trace default-on (opt-out rather than opt-in)? +- [ ] Does the trace clearly identify your brand? +- [ ] Can the trace be seen in the course of normal daily activity (not just in niche contexts)? + +## The Apple Logo Story: Designing for the Observer + +One of the most instructive examples of Public design is Apple's decision about the MacBook logo orientation. + +### The Decision + +In the early days of laptops, the Apple logo on the MacBook lid was oriented so that it appeared right-side-up to the user when they opened the laptop. This meant that when the laptop was open and in use, the logo appeared upside-down to everyone looking at it. + +Apple made a deliberate decision to flip the logo. The current design shows the Apple logo right-side-up to observers — the people in the coffee shop, the meeting room, the library — rather than to the user. + +### Why It Matters + +**The user already knows they have a Mac.** They don't need the logo to face them. But every observer who sees the glowing Apple logo is a potential customer being influenced by social proof. + +**The calculation:** +- User sees the logo: 1 person influenced (who is already a customer) +- Observers see the logo: 10-50 people influenced per day (who may be potential customers) + +Apple chose to optimize for the observer, not the user. Every open MacBook became a billboard. + +### The Design Lesson + +**Always ask: Who is the audience for the visible element — the user or the observer?** + +| Design Decision | User-Facing | Observer-Facing | Better for Growth | +|----------------|-------------|-----------------|-------------------| +| Logo placement | Logo right-side-up for user | Logo right-side-up for viewer | Observer-facing | +| Product color | User's preferred color | Distinctive, recognizable color | Observer-facing (if distinctive) | +| Sound/notification | Subtle for user | Recognizable to bystanders | Observer-facing (iPhone ring) | +| Packaging | Easy to open | Distinctive to see someone carrying | Both (Apple bags) | + +## Self-Advertising Products + +The most powerful form of Public design is a product that advertises itself simply through normal use. Every use generates exposure to non-users. + +### Classic Self-Advertising Products + +| Product | Self-Advertising Mechanism | Exposure Per Use | +|---------|--------------------------|-----------------| +| **Hotmail** | "Get your free email at Hotmail" in every email signature | Every email recipient | +| **iPhone** | "Sent from my iPhone" default signature | Every email/text recipient | +| **Apple products** | Distinctive white earbuds, glowing logo | Everyone in visual range | +| **Beats headphones** | Large, colorful, distinctive design | Everyone in visual range | +| **Tesla** | Distinctive design, no exhaust, door handles | Every driver and pedestrian nearby | +| **Zoom** | Watermark on free tier, "Zoom Meeting" in calendar | Every meeting participant | +| **Canva** | "Made with Canva" on free-tier designs | Every viewer of the design | + +### Designing Self-Advertising Features + +**Method 1: Output branding.** If your product creates something that others see, brand the output. + +| Product Type | Output | Branding Opportunity | +|-------------|--------|---------------------| +| Email tool | Emails sent | Email signature/footer | +| Design tool | Graphics, documents | Watermark or "Made with" tag | +| Website builder | Live websites | "Powered by" footer | +| Survey tool | Surveys sent | Branded survey pages | +| Scheduling tool | Calendar invites | "Scheduled with [tool]" | +| Video tool | Recorded videos | Intro/outro card | + +**Method 2: Distinctive physical design.** Make the product visually distinctive so usage is immediately recognizable. + +**Method 3: Audible signatures.** Create recognizable sounds — the Intel chime, the iPhone ringtone, the Skype call sound — that signal product usage to bystanders. + +**Method 4: Usage signals.** Create visible indicators of product usage — typing indicators in chat, "currently playing" in music apps, live status in collaboration tools. + +## The Livestrong Wristband Case Study + +The Livestrong yellow wristband is one of the most successful examples of the Public principle in action. + +### What They Did + +In 2004, Nike and the Lance Armstrong Foundation launched a simple yellow silicone wristband for $1 to raise money for cancer research. The initial goal was to sell 5 million. They sold 85 million. + +### Why It Worked (Public Principle Analysis) + +**Observable consumption:** Unlike a donation (private), wearing a wristband is public. Everyone can see it on your wrist — at work, at the gym, at school, in conversation. + +**Behavioral residue:** The wristband outlasts the moment of donation. You donate once, but you wear the wristband for months or years. Every day of wearing is a day of advertising. + +**Self-advertising:** The wristband sparked conversations. "What's that yellow bracelet?" led to conversations about cancer awareness, which led to more purchases. + +**Social proof cascade:** As more people wore them, more people wanted them. Visibility created demand, which created more visibility. The cycle was self-reinforcing. + +**Identity signaling:** Wearing the wristband said "I care about cancer research" — a positive identity signal. It was social currency expressed through a public artifact. + +### Key Design Elements + +| Element | Design Choice | Why It Mattered | +|---------|--------------|----------------| +| **Color** | Bright yellow — distinctive and noticeable | Stood out against any clothing, immediately identifiable | +| **Material** | Silicone — comfortable for all-day wear | Removed barrier to continuous display | +| **Price** | $1 — minimal barrier to entry | Anyone could participate | +| **Simplicity** | No text visible from distance, just the color | The color itself became the symbol | +| **Wearability** | Wrist — always visible in daily activities | Maximum exposure surface | + +## "Built to Show" Design Principles + +A systematic approach to designing products and features for public visibility. + +### Principle 1: Default to Visible + +| Decision | Invisible Option | Visible Option | Choose | +|----------|-----------------|----------------|--------| +| User achievements | Private profile | Public profile with opt-out | Visible | +| Product outputs | Unbranded | Branded with opt-out | Visible | +| Usage status | Hidden | "Currently using [product]" | Visible | +| Milestones | Internal notification | Shareable card | Visible | + +### Principle 2: Design for the Bystander + +Every product interaction has at least two audiences: the user and the observer. Design elements that communicate to the observer. + +**The bystander checklist:** +- [ ] When someone uses your product in public, what does a bystander see? +- [ ] Can the bystander identify the product from what they observe? +- [ ] Does the observation create curiosity ("What's that?" / "How do I get that?")? +- [ ] Is the observation positive (does the user look good using it)? + +### Principle 3: Create Observable Social Proof + +| Social Proof Type | How to Make It Observable | Example | +|------------------|--------------------------|---------| +| **Usage numbers** | Display live user count | "Join 10M+ users" on sign-up page | +| **Expert endorsement** | Visible badges or certifications | "Recommended by [authority]" badge | +| **Peer adoption** | Show which friends/colleagues use it | "5 of your contacts are on [app]" | +| **Activity feeds** | Public stream of user actions | GitHub commit history, Strava activity feed | +| **Waitlist length** | Display waitlist position | "You're #4,521 in line" | + +### Principle 4: Turn Private Into Public (Ethically) + +For products with inherently private usage, find ethical ways to create public signals. + +| Private Product | Public Signal Approach | Implementation | +|----------------|----------------------|----------------| +| Meditation app | Streak badge for social profiles | "Meditator: 365-day streak" badge | +| Financial tool | Aggregate achievement sharing | "This community saved $10M this year" | +| Health app | Anonymized collective milestones | "Our users walked to the moon and back — 3 times" | +| Learning platform | Certification badges | Shareable LinkedIn credentials | +| Therapy/Counseling | Community awareness campaigns | "I believe in mental health" shareable frames | + +**Ethical boundaries:** +- Never make private health, financial, or personal data public without explicit consent +- Default privacy for sensitive information, default visibility for achievements +- Let users control exactly what is visible and to whom +- Celebrate the activity, not the underlying condition + +## Observability Audit + +Use this audit to evaluate how visible your product is to non-users. + +### Audit Checklist + +| Dimension | Question | Score (0-10) | +|-----------|----------|-------------| +| **Physical visibility** | Can bystanders see when someone uses your product? | | +| **Digital visibility** | Do your product's outputs carry branding others can see? | | +| **Behavioral residue** | Does your product leave traces that outlast the usage moment? | | +| **Self-advertising** | Does normal product usage automatically expose non-users to the brand? | | +| **Distinctive design** | Is your product visually/audibly recognizable from a distance? | | +| **Social proof display** | Can potential users see how many others are already using it? | | +| **Share packaging** | Are achievements and outputs pre-packaged for easy sharing? | | + +**Scoring:** +- **0-20:** Invisible product. Growth relies entirely on direct marketing. Major opportunity. +- **21-40:** Partially visible. Some organic exposure but significant gaps. +- **41-55:** Highly visible. Strong organic growth through observation and imitation. +- **56-70:** Maximally visible. Product is a walking billboard. Organic growth machine. + +## Exercises + +### Exercise 1: The Bystander Test + +Have someone use your product in a public setting (coffee shop, office, commute). Sit nearby and observe: Can you tell what product they're using? What's visible? What's invisible? Interview 3 bystanders: Did they notice anything? What did they assume? + +### Exercise 2: Residue Inventory + +List every trace your product leaves after use. For each trace, rate its visibility (1-10), duration (hours/days/months), and brand clarity (1-10). Identify the strongest residue and invest in amplifying it. Identify gaps where residue could be added. + +### Exercise 3: The Apple Logo Question + +For every user-facing design element, ask: "Is this oriented for the user or the observer?" Identify at least one element that should be reoriented for the observer. Implement the change and measure the impact on new user acquisition. + +### Exercise 4: Self-Advertising Feature Design + +Design a feature that makes your product advertise itself through normal use. It must meet all four criteria: (1) visible to non-users, (2) clearly branded, (3) useful or attractive enough that users don't remove it, and (4) creates curiosity in observers. Sketch the feature, plan the implementation, and define how you'll measure its impact on organic growth. diff --git a/.agents/skills/contagious/references/social-currency.md b/.agents/skills/contagious/references/social-currency.md new file mode 100644 index 00000000..910cf16f --- /dev/null +++ b/.agents/skills/contagious/references/social-currency.md @@ -0,0 +1,190 @@ +# Social Currency: Making People Look Good by Sharing + +Social currency is the idea that people share things that make them look good to others. Just as we use money to buy products and services, we use social currency to achieve desired positive impressions among our families, friends, and colleagues. Understanding and engineering social currency is one of the most powerful levers for word-of-mouth. + +## Why Social Currency Drives Sharing + +People are fundamentally self-interested communicators. Research shows that over 40% of what people talk about is their personal experiences and opinions. Why? Because sharing personal opinions activates the brain's reward centers — the same areas associated with food, money, and other primary rewards. Talking about ourselves and our discoveries literally feels good. + +This means people don't share your product because they want to help you. They share it because sharing it makes *them* look good — smart, funny, in-the-know, generous, ahead of the curve. Your job is to make sharing your product a form of self-enhancement. + +Three mechanisms drive social currency: + +1. **Remarkability** — sharing something surprising makes you seem interesting +2. **Game mechanics** — sharing achievements makes you seem accomplished +3. **Exclusivity** — sharing insider knowledge makes you seem connected + +## Remarkability: Violating Expectations + +Remarkable things are, by definition, things worth remarking on. They violate expectations. They surprise. They make people say "No way!" or "Did you know...?" + +### How to Find the Remarkable Angle + +The key insight is that remarkability is not an inherent property of the product — it is a property of the framing. Even mundane products can become remarkable with the right angle. + +**The Remarkability Matrix:** + +| Strategy | How It Works | Example | +|----------|-------------|---------| +| **Surprising extreme** | Push a known attribute to an unexpected extreme | Barclay Prime's $100 cheesesteak (cheesesteaks are cheap, this one isn't) | +| **Surprising juxtaposition** | Combine two things that don't normally go together | A blender that destroys an iPhone (Blendtec) | +| **Hidden truth** | Reveal something people didn't know about something familiar | "Did you know honey never spoils?" | +| **Counter-intuitive fact** | Share data that contradicts common belief | "93% of word-of-mouth happens offline, not on social media" | +| **Record-breaking** | Be the biggest, smallest, fastest, first | "The world's spiciest chip" (Paqui One Chip Challenge) | +| **Mystery or secret** | Reveal something previously hidden | Secret menus at In-N-Out | + +### The "Did You Know" Test + +Ask yourself: Can a customer start a sentence with "Did you know...?" or "You won't believe this, but..." about your product? If yes, you have remarkability. If no, you need to engineer it. + +**Examples:** +- "Did you know there's a bar you can only get into through a phone booth?" (Please Don't Tell, NYC speakeasy) +- "Did you know Snapchat messages disappear after you read them?" (early Snapchat) +- "Did you know this blender can blend a rake handle?" (Blendtec) + +### Inner Remarkability Exercise + +Every product has an inner remarkability waiting to be found. Use this exercise to uncover it. + +**Step 1: List 10 facts about your product or company.** Include manufacturing details, origin stories, ingredient sourcing, engineering decisions, team backgrounds, customer results — anything. + +**Step 2: For each fact, rate it on the "surprise scale"** (1 = everyone knows this, 10 = nobody would guess this). + +**Step 3: Take the top 3 most surprising facts and frame them as "Did you know...?" statements.** + +**Step 4: Test them.** Tell five people. Watch their faces. If they lean in, raise eyebrows, or immediately want to share it with someone, you found your remarkability. + +| Product | Mundane Description | Remarkable Reframe | +|---------|--------------------|--------------------| +| Cloud storage | "We store your files online" | "We have more data than the Library of Congress — and it's all yours" | +| Running shoes | "Comfortable performance footwear" | "Each shoe is made from 11 recycled plastic bottles" | +| Accounting software | "Track your business expenses" | "Our users find an average of $4,200 in missed tax deductions" | +| Coffee brand | "Premium single-origin coffee" | "Our beans are aged in whiskey barrels for 30 days" | + +## Game Mechanics: Leaderboards, Badges, and Status + +Game mechanics tap into our innate desire for achievement, status, and comparison. They make internal accomplishments externally visible — and therefore shareable. + +### Core Game Mechanics for Social Currency + +| Mechanic | How It Works | Sharing Trigger | Example | +|----------|-------------|----------------|---------| +| **Leaderboards** | Rank users against each other | "I'm in the top 5%!" | Fitbit weekly step rankings | +| **Badges/Achievements** | Visual markers of accomplishment | "I just earned [badge]!" | Foursquare mayorships | +| **Levels/Tiers** | Progressive status milestones | "I just reached [level]!" | Airline frequent flyer tiers | +| **Streaks** | Consecutive-day engagement counts | "I'm on a 365-day streak!" | Duolingo streaks, Snapchat streaks | +| **Progress bars** | Visual completion indicators | "I'm 90% to [goal]!" | LinkedIn profile completeness | +| **Milestones** | Numerical achievement markers | "I just hit 10,000 steps!" | Fitbit, Apple Watch rings | + +### Designing Effective Game Mechanics + +**Principle 1: Make the metric meaningful.** "You've completed 50 tasks" matters more than "You've logged in 50 times." Tie achievements to outcomes users care about. + +**Principle 2: Make sharing effortless.** Pre-generate beautiful share cards. Don't make users screenshot and crop. One tap should produce a ready-to-share image or post. + +**Principle 3: Make comparison possible.** "You're in the top 3% of readers this year" is more shareable than "You read 52 books." Relative positioning creates social currency. + +**Principle 4: Reset periodically.** Annual resets (like Spotify Wrapped) give people a fresh reason to share every year. Permanent achievements lose their novelty. + +### The Spotify Wrapped Effect + +Spotify Wrapped is perhaps the most successful modern example of game mechanics driving social currency. Every December, Spotify gives each user a personalized summary of their listening habits — top artists, total minutes, genres, and quirky insights. + +**Why it works:** +- It's personalized (unique to each user) +- It's comparative ("You listened more than 95% of users") +- It's identity-signaling ("My top genre is indie folk" says something about who I am) +- It's time-limited (only available once a year, creating urgency) +- It's pre-packaged for sharing (beautiful cards formatted for Instagram Stories) + +**Design checklist for your own "Wrapped" moment:** +- [ ] Aggregate meaningful user data over a period +- [ ] Frame data in terms of achievements and comparisons +- [ ] Create visual share cards formatted for major platforms +- [ ] Include at least one surprising or humorous insight +- [ ] Release it at a predictable, anticipated time +- [ ] Make sharing one tap from the reveal screen + +## Exclusivity and Scarcity: The Insider Effect + +People value things more when access is restricted. But more importantly for word-of-mouth, exclusivity gives people something special to talk about — insider knowledge that others don't have. + +### Three Types of Exclusivity + +| Type | Mechanism | Example | WOM Driver | +|------|-----------|---------|-----------| +| **Access exclusivity** | Limited who can get in | Gmail invite-only launch, Clubhouse | "I have something you can't get" | +| **Information exclusivity** | Limited who knows | In-N-Out secret menu, speakeasy bars | "I know something you don't" | +| **Temporal exclusivity** | Limited when available | McDonald's McRib, seasonal products | "It's only here for a short time" | + +### The Paradox of Exclusivity + +Exclusivity only generates word-of-mouth if people can talk about it. A truly secret product generates zero WOM. The key is creating the *feeling* of exclusivity while still allowing — even encouraging — people to talk about their insider status. + +**Design pattern:** Make the *access* exclusive but the *knowledge* of its existence public. Everyone should know about the speakeasy; only a few should be able to get in. That imbalance drives conversation. + +### Exclusivity Design Checklist + +- [ ] Is there something about your product that only some people know or can access? +- [ ] Can insiders signal their status to outsiders without gatekeeping harshly? +- [ ] Does the exclusivity make people feel genuinely special (not just artificially restricted)? +- [ ] Is there a path for outsiders to become insiders (maintaining aspiration)? +- [ ] Does sharing insider status enhance the sharer's image? + +## Identity Signaling + +People use products and brands to signal who they are. The brands we choose, the content we share, and the products we use are all identity markers. + +### The Identity Signaling Framework + +| Signal Type | What It Communicates | Product Design Implication | +|------------|---------------------|---------------------------| +| **Taste** | "I have good taste" | Premium design, curated selection | +| **Intelligence** | "I'm smart/informed" | Data, insights, non-obvious information | +| **Values** | "I care about X" | Mission-driven branding, cause alignment | +| **Status** | "I'm successful" | Visible quality markers, premium tier | +| **Belonging** | "I'm part of this tribe" | Community identity, shared language | +| **Pioneering** | "I'm ahead of the curve" | Early access, beta programs, "first to try" | + +### Designing for Identity Signaling + +**Ask:** When someone shares or uses your product, what does it say about them? If the answer is "nothing," you have an identity signaling gap. + +**The "bumper sticker" test:** Would someone proudly put your brand on their laptop, water bottle, or social media bio? If yes, your brand has become an identity signal. If no, you need to strengthen what your brand says about its users. + +## Social Currency Audit + +Run this audit on your product or campaign: + +| Dimension | Question | Score (0-10) | Improvement | +|-----------|----------|-------------|-------------| +| **Remarkability** | Is there a "Did you know...?" fact about it? | | | +| **Game mechanics** | Are there visible achievements users can share? | | | +| **Exclusivity** | Do users feel like insiders? | | | +| **Identity signaling** | Does using/sharing it say something positive about the sharer? | | | +| **Share packaging** | Is it easy to share (one tap, beautiful format)? | | | +| **Comparison** | Can users compare themselves to others? | | | + +**Scoring guide:** +- **0-15:** Minimal social currency. People have no reason to talk about you. +- **16-30:** Some social currency. Occasional mentions, but not systematic. +- **31-45:** Strong social currency. Regular word-of-mouth driven by self-enhancement. +- **46-60:** Exceptional social currency. Users actively seek opportunities to share and signal. + +## Exercises + +### Exercise 1: Find Your Inner Remarkability + +List 10 non-obvious facts about your product, company, or industry. Score each on surprise (1-10). Take the top 3 and craft "Did you know...?" statements. Test with 5 people and observe reactions. + +### Exercise 2: Design Your Wrapped Moment + +What data do you collect about users? Design a yearly, monthly, or weekly summary that highlights their accomplishments in a visually shareable format. Sketch the share card. What would make someone *want* to post it? + +### Exercise 3: Create an Insider Program + +Design an exclusivity layer for your product. What would the "secret menu" be? What would "invite-only access" look like? How would insiders signal their status? Map the insider-to-outsider conversation flow. + +### Exercise 4: The Identity Signal Test + +Complete this sentence for 5 of your most engaged users: "By sharing [your product/content], they're telling the world they are ___." If you can't complete it, your product lacks identity signaling. Redesign so using and sharing your product makes a statement about the sharer's identity. diff --git a/.agents/skills/contagious/references/stories-trojan-horse.md b/.agents/skills/contagious/references/stories-trojan-horse.md new file mode 100644 index 00000000..6aae9a07 --- /dev/null +++ b/.agents/skills/contagious/references/stories-trojan-horse.md @@ -0,0 +1,251 @@ +# Stories as Trojan Horses: Embedding Your Brand in Narrative + +People don't share information — they tell stories. Stories are the vessels that carry ideas, morals, and brand messages through populations. The most effective word-of-mouth strategy isn't to get people to share your product information directly; it's to embed your brand inside a story so compelling that people retell it — and your brand comes along for the ride. + +## The Trojan Horse Principle + +A Trojan Horse story is a narrative that carries your brand message inside it, hidden within entertainment, emotion, or intrigue. The listener absorbs the brand message while being transported by the story — just as the Greeks entered Troy hidden inside a gift. + +**The critical requirement:** The brand must be so integral to the story that you cannot retell the story without mentioning the brand. If the brand can be swapped out or removed and the story still works, the Trojan Horse has failed. + +### The Brand Integration Test + +This is the single most important test for any branded story: + +**Ask:** "Can someone retell this story without mentioning our brand?" + +| Answer | Verdict | Example | +|--------|---------|---------| +| **No — the brand is essential** | Story passes. Brand is integral. | "Blendtec blended an iPhone" — you can't tell this without saying "Blendtec" | +| **Yes — the brand is incidental** | Story fails. Brand is a footnote. | A funny Super Bowl ad — people retell the joke but forget the brand | +| **Yes — but the brand adds detail** | Partial pass. Brand is mentioned but forgettable. | "Some company did a cool stunt" — brand isn't essential to the narrative | + +### Why Most Branded Stories Fail + +The most common failure mode is creating a story that's too good at being entertaining and not good enough at carrying the brand. The story overshadows the message. + +**The Evian Roller Babies problem:** Evian created a viral video of babies roller skating that became one of the most-viewed ads in YouTube history. People loved it. They shared it millions of times. But sales of Evian water declined during the campaign period. Why? Because the babies were the story. You could retell "I saw this hilarious video of babies roller skating" without ever mentioning Evian. The Trojan Horse was empty. + +**The anti-pattern:** Story entertainment value is inversely correlated with brand recall when the brand is not structurally integrated into the narrative. + +| Scenario | Story Quality | Brand Integration | Result | +|----------|-------------|------------------|--------| +| Blendtec "Will It Blend?" | High | High (brand IS the story) | Massive sales lift | +| Evian Roller Babies | Very high | Low (brand is incidental) | High views, declining sales | +| Old Spice "The Man Your Man Could Smell Like" | Very high | High (product is central) | Massive sales lift | +| GoDaddy Super Bowl ads | Medium-high | Low (shock value, not brand) | Awareness without brand association | + +## The Blendtec "Will It Blend?" Case Study + +This is the gold standard for Trojan Horse storytelling. + +### What They Did + +Tom Dickson, founder of Blendtec, created a YouTube series where he blended increasingly extreme objects in his company's blender — iPhones, golf balls, glow sticks, a rake handle, marbles, even a Justin Bieber CD. + +### Why It's a Perfect Trojan Horse + +**The story IS the product.** You cannot tell someone about "Will It Blend?" without explaining that a powerful blender destroyed an iPhone. The brand claim (extreme blending power) is the punchline of the story. + +**Multiple STEPPS activation:** +- **Social Currency:** "Did you see them blend an iPhone?" makes the sharer seem plugged in +- **Emotion:** Amusement (high-arousal positive) from the absurdity of blending an iPad +- **Stories:** The narrative is irresistible and retellable in one sentence +- **Public:** YouTube views, shares, and embeds made it highly visible +- **Practical Value:** Demonstrates product capability (implicit: "Imagine what it does to food") + +**The retelling test:** Try retelling this story without saying "Blendtec" or "blender." You can't. The blender is the protagonist. That's a perfect Trojan Horse. + +### Results + +- YouTube channel amassed hundreds of millions of views +- Retail sales of Blendtec blenders increased by 700% +- Created a media property that generated content for years +- Cost per video: approximately $50-100 (the cost of the blended items) + +## Narrative Templates for Brand Integration + +### Template 1: The Remarkable Product Demonstration + +**Structure:** [Brand/Product] does [extreme version of its core function] that nobody expected. + +**Why it works:** The product capability IS the story. Removing the product removes the story. + +**Examples:** +- Blendtec blending an iPhone (extreme blending) +- FedEx delivering a package to the top of Mount Everest (extreme delivery) +- Gorilla Glass surviving extreme drop tests (extreme durability) + +**How to apply:** What is the most extreme, surprising, or impressive thing your product can do? That's your story. + +### Template 2: The Audacious Stunt + +**Structure:** [Brand] created/offered [something so extreme/unexpected] that people had to talk about it. + +**Why it works:** The stunt is so remarkable that it becomes a story, and the brand is the author of the stunt. + +**Example: Barclay Prime's $100 Cheesesteak** + +Barclay Prime, a new Philadelphia restaurant, needed buzz. In a city obsessed with cheesesteaks (typically $5-10), they created a $100 cheesesteak made with Kobe beef, lobster tail, truffles, and champagne. + +**Why it's a perfect story:** +- The extreme price (vs. the $5 norm) creates remarkability +- You can't retell "I had a $100 cheesesteak" without saying "at Barclay Prime" +- It activated Social Currency (insider dining experience) + Stories (retellable narrative) +- Every food blogger, journalist, and diner had a story to tell — and Barclay Prime was always in it + +### Template 3: The Origin Story + +**Structure:** [Founder] faced [relatable problem] and created [product] because [compelling reason]. + +**Why it works:** Origin stories humanize brands. When the product was born from a genuine human struggle, the story and the brand are inseparable. + +**Examples:** +- Sara Blakely cutting the feet off her pantyhose, leading to Spanx +- Steve Jobs building computers in a garage +- Airbnb founders renting air mattresses to pay rent + +**How to apply:** What's the true story of why your product exists? If it started with a personal pain point, that's your narrative. The pain point must naturally lead to the product as the resolution. + +### Template 4: The Customer Hero Story + +**Structure:** [Customer] had [problem]. They used [product]. Now [remarkable outcome]. + +**Why it works:** The customer is the hero, but the product is the weapon that enabled their transformation. You can't retell the hero's journey without mentioning the tool. + +**Key requirement:** The outcome must be remarkable enough to be worth retelling. "Saved 10 minutes" is not a story. "Grew from 0 to $1M in revenue using [tool]" is a story. + +### Template 5: The Unexpected Use Case + +**Structure:** Someone used [product] for [completely unexpected purpose] and [surprising result]. + +**Why it works:** The juxtaposition of product and use case is inherently surprising and retellable. + +**Example:** Using WD-40 to remove a python wrapped around a bus chassis. The story is bizarre, memorable, and impossible to tell without mentioning WD-40. + +## Anti-Patterns: Stories That Fail + +### Anti-Pattern 1: The Story Overshadows the Brand + +**Symptom:** People remember the story vividly but can't recall the brand. + +**Cause:** Story entertainment value is decoupled from brand relevance. + +**Fix:** Restructure so the brand is the protagonist, the tool, or the punchline — not just the sponsor. + +| Failing Version | Fixed Version | +|----------------|--------------| +| "This hilarious ad showed a man riding a horse backward" (brand: ???) | "Old Spice showed the man your man could smell like" (brand: Old Spice) | +| "There was a great video of babies roller skating" (brand: ???) | No easy fix — the babies ARE the story, not the water | +| "A company did a funny Super Bowl ad" (brand: ???) | Make the product the source of the humor, not the backdrop | + +### Anti-Pattern 2: The Brand Hijacks the Story + +**Symptom:** The story feels like a thinly veiled advertisement. People tune out or feel manipulated. + +**Cause:** Too much brand emphasis, not enough genuine narrative value. + +**Fix:** Lead with the story. Let the brand emerge naturally from the narrative. If you have to force the brand mention, the integration isn't working. + +### Anti-Pattern 3: The Story Is Too Complex to Retell + +**Symptom:** Great story, but it requires 5 minutes to explain. Nobody retells it. + +**Cause:** Too many plot points, characters, or nuances. + +**Fix:** Simplify to one sentence. If you can't summarize the story in one sentence that includes the brand, simplify until you can. + +**The one-sentence test:** +- "Blendtec blended an iPhone in their blender." (Pass) +- "This restaurant in Philly sells a $100 cheesesteak." (Pass — "which restaurant?" leads to brand mention) +- "There's this 7-minute video about a guy who travels the world and encounters various challenges and ultimately realizes that the real journey was inside him and also the airline was really great." (Fail) + +### Anti-Pattern 4: The Story Is Not True + +**Symptom:** Initial buzz followed by backlash when the truth emerges. + +**Cause:** Fabricated origin stories, fake testimonials, staged "real" moments. + +**Fix:** Use true stories. They are more compelling anyway because they carry the weight of authenticity. If you need to embellish, do it with acknowledged creative license, not deception. + +## Building a Story Engine + +Rather than creating one story, build a system that generates stories continuously. + +### The Story Engine Framework + +| Component | What It Is | Example | +|-----------|-----------|---------| +| **Story format** | A repeatable structure | "Will It Blend?" series format | +| **Content calendar** | Regular story cadence | New blend every 2 weeks | +| **Escalation mechanism** | Each story more remarkable than the last | iPhone to iPad to Skeleton to... | +| **Audience participation** | Let the audience suggest stories | "What should we blend next?" | +| **Distribution plan** | Where and how stories are shared | YouTube + social + PR | + +### Designing Your Story Engine + +**Step 1: Define your story format.** What repeatable structure can showcase your product? It should be simple, reproducible, and brand-integral. + +**Step 2: Create an escalation path.** Each new installment should top the last. Start moderate and build to extreme. This creates anticipation and a reason to follow. + +**Step 3: Build audience participation.** Let your audience co-create the story. This generates Social Currency (they're part of it), Emotion (investment in the outcome), and Public visibility (they share their suggestions and the results). + +**Step 4: Plan distribution.** Stories don't spread themselves. Seed them in the right channels. YouTube for video, Twitter for real-time commentary, email for loyal followers, PR for mainstream reach. + +## Valuable Virality + +Not all viral stories create business value. A story that spreads without carrying the brand message is a vanity metric. + +### The Valuable Virality Test + +| Question | If Yes | If No | +|----------|--------|-------| +| Does the story spread? | Virality achieved | Story is not compelling enough | +| Does the story carry the brand? | Valuable virality | Entertaining but brand-irrelevant | +| Does the story drive action? | Business impact | Awareness without conversion | +| Can the story be told repeatedly? | Sustained value | One-time spike | + +**The goal:** All four "Yes" answers. Anything less means you're leaving value on the table. + +### Optimizing for Valuable Virality + +1. **Start with the brand integration.** Don't create a great story and then try to insert the brand. Start with the brand truth and build the story around it. +2. **Make the brand the resolution.** In the narrative arc, the brand should be what resolves the tension. Without it, the story is incomplete. +3. **Include a clear next step.** After hearing the story, what should someone do? Visit a website? Try the product? The story should naturally lead to action. + +## Story Audit + +Evaluate any branded story for Trojan Horse effectiveness. + +| Dimension | Question | Score (0-10) | +|-----------|----------|-------------| +| **Retellability** | Can the story be retold in one sentence? | | +| **Brand integration** | Is the brand essential to the story (Trojan Horse test)? | | +| **Emotional arousal** | Does the story evoke high-arousal emotion? | | +| **Authenticity** | Is the story true (or acknowledged as creative)? | | +| **Simplicity** | Can anyone understand and retell it without expertise? | | +| **Escalation** | Does the story format support a series or follow-up? | | + +**Scoring:** +- **0-20:** Weak story. Brand is easily forgotten in retelling. +- **21-40:** Moderate story. Brand is mentioned but not essential. +- **41-50:** Strong Trojan Horse. Brand is integral to the narrative. +- **51-60:** Perfect Trojan Horse. Impossible to retell without the brand. Story engine potential. + +## Exercises + +### Exercise 1: The Retelling Test + +Tell your brand's story to 5 people. Wait one week. Ask them to retell it to you. Did they include your brand name? If they told the story without the brand, your integration failed. Redesign. + +### Exercise 2: One-Sentence Story + +Write your brand story in one sentence that includes the brand name and is interesting enough that someone would retell it at a dinner party. If you can't, simplify until you can. + +### Exercise 3: Story Format Design + +Design a repeatable story format for your brand (like "Will It Blend?"). Define: the format structure, the brand integration point, the escalation mechanism, and the audience participation element. Create the first three installments. + +### Exercise 4: Anti-Pattern Audit + +Review your last 5 branded content pieces. For each, apply the Trojan Horse test. Categorize each as: perfect integration, partial integration, or brand-irrelevant entertainment. For any that fail, redesign using the templates above. diff --git a/.agents/skills/contagious/references/triggers.md b/.agents/skills/contagious/references/triggers.md new file mode 100644 index 00000000..0f3e054f --- /dev/null +++ b/.agents/skills/contagious/references/triggers.md @@ -0,0 +1,240 @@ +# Triggers: Designing Environmental Cues for Top-of-Mind Awareness + +Triggers are stimuli in the environment that prompt people to think about related things. If your product is linked to a frequent trigger, people will think about it more often — and what's top-of-mind becomes tip-of-tongue. Triggers are the most underestimated of the STEPPS principles, yet they may be the most powerful driver of sustained word-of-mouth. + +## Why Triggers Matter More Than You Think + +Most marketers obsess over making their product exciting. But excitement fades. Triggers persist. + +Consider this: Rebecca Black's "Friday" — widely considered one of the worst songs ever made — sees a reliable spike in YouTube views every single Friday. Not because people suddenly like the song more on Fridays, but because the day of the week triggers thoughts of it. The environmental cue (Friday) keeps it top-of-mind on a weekly cycle. + +**The core insight:** Products that are linked to frequent environmental triggers get more word-of-mouth than products that are more exciting but lack triggers. Frequency of trigger beats strength of association. + +This is why Kit Kat linking itself to coffee breaks was genius — not because coffee and Kit Kat are a natural pairing, but because coffee breaks happen multiple times per day, every day. Each break is a trigger. + +## The Kit Kat + Coffee Case Study + +In 2007, Kit Kat was struggling. Sales had been declining. The brand needed a new approach. + +**What they did:** Kit Kat repositioned itself as the companion to coffee. "Have a break, have a Kit Kat" was paired with coffee in every ad, display, and message. The idea was simple: link Kit Kat to something people already do frequently — drink coffee. + +**Why it worked:** +- Coffee is consumed 2-3 times per day by most adults +- Coffee breaks are a social ritual (often involving conversation) +- The physical environment of coffee (mugs, shops, machines) serves as a persistent visual trigger +- The association was easy to form (break + coffee + Kit Kat) + +**The result:** Kit Kat sales increased significantly after the campaign. The product itself didn't change. The chocolate didn't taste better. But by linking to a frequent environmental cue, Kit Kat became top-of-mind multiple times per day. + +**The lesson:** You don't need to make your product more exciting. You need to link it to something people encounter frequently. + +## Habitat Analysis: Where and When Is Your Trigger? + +A trigger's "habitat" is the environment where it naturally occurs. The more frequently people enter that habitat, the more frequently they'll be triggered to think about your product. + +### The Habitat Analysis Framework + +**Step 1: Map your product's natural context.** When and where do people use your product or encounter the problem it solves? + +**Step 2: Identify the environmental elements present in that context.** What do people see, hear, smell, or do in that moment? + +**Step 3: Evaluate each element as a potential trigger.** How frequent is it? How strongly does it already associate with something else? Can you own it? + +**Step 4: Select the most frequent, ownable trigger and systematically link your product to it.** + +| Habitat Element | Frequency | Existing Association | Ownability | Trigger Score | +|----------------|-----------|---------------------|------------|---------------| +| Morning alarm | Daily | Waking up, grogginess | Medium | 7/10 | +| Coffee machine | 2-3x/day | Energy, break time | High (Kit Kat proved it) | 9/10 | +| Red traffic light | Multiple/day | Waiting, frustration | High (largely unowned) | 8/10 | +| Friday afternoon | Weekly | Weekend anticipation | Medium (many competitors) | 6/10 | +| Rain | Variable | Staying inside, cozy | Medium | 5/10 | + +### Habitat Analysis Worksheet + +Complete this for your product: + +1. **Primary use context:** When and where does someone use your product? + - Time of day: ___ + - Location: ___ + - Activity: ___ + - Emotional state: ___ + +2. **Environmental elements in that context:** + - What they see: ___ + - What they hear: ___ + - What they touch/hold: ___ + - What they're doing before/after: ___ + +3. **Adjacent triggers (things nearby but not directly related):** + - Physical objects: ___ + - Routines: ___ + - Other products: ___ + - Times/days: ___ + +4. **Frequency ranking:** Rate each element by how often people encounter it (daily > weekly > monthly > rarely). + +5. **Selection:** Choose the most frequent element that you can plausibly own as a trigger. + +## Trigger Frequency Matrix + +Not all triggers are created equal. The frequency and strength of a trigger determine its word-of-mouth impact. + +| | **High Frequency** | **Low Frequency** | +|---|---|---| +| **Strong Association** | **Gold Mine** — Daily trigger strongly linked to your product. Maximum WOM. | **Wasted Potential** — Strong link but rare encounters. Spiky WOM. | +| **Weak Association** | **Opportunity** — Frequent trigger, weak link. Invest in building the association. | **Avoid** — Rare trigger, weak link. Not worth the investment. | + +### Examples by Quadrant + +**Gold Mine (High Frequency + Strong Association):** +- Kit Kat + coffee breaks (2-3x/day, strong link) +- Budweiser + watching sports (weekly+ for fans, strong link) +- "That's hot" + Paris Hilton (early 2000s — phrase used constantly, strong link) + +**Wasted Potential (Low Frequency + Strong Association):** +- Turkeys + Thanksgiving (strong link, but once a year) +- Fireworks + 4th of July (strong, but annual) +- Pumpkin spice + fall (strong, but seasonal) + +**Opportunity (High Frequency + Weak Association):** +- Commute time + [unlinked product] (daily, ready to be claimed) +- Lunch break + [unlinked product] (daily, largely unowned) +- Waiting in line + [unlinked product] (frequent, opportunity to link) + +**Avoid (Low Frequency + Weak Association):** +- Eclipses + [product] (extremely rare, no natural link) +- Leap year + [product] (every 4 years, no link) + +## Trigger Design Process + +A systematic process for creating and reinforcing triggers. + +### Step 1: Identify the Trigger Candidate + +Select an environmental cue that: +- Occurs frequently (daily or more is ideal) +- Is present in or near your product's use context +- Is not strongly owned by a competitor +- Can be plausibly linked to your product + +### Step 2: Create the Link + +Build the association between your product and the trigger through repetition and co-occurrence. + +| Linking Method | How It Works | Example | +|---------------|-------------|---------| +| **Advertising co-occurrence** | Show product alongside trigger in every ad | Kit Kat always shown with coffee | +| **Physical proximity** | Place product near the trigger in the real world | Candy at checkout counters (impulse trigger) | +| **Verbal anchoring** | Use taglines that embed the trigger | "Have a break, have a Kit Kat" | +| **Digital pairing** | Trigger-timed push notifications or content | "It's Friday — time for your weekly review" | +| **Experiential linking** | Create events or experiences that pair the two | Sampling coffee + Kit Kat at offices | + +### Step 3: Reinforce Consistently + +The trigger link weakens without reinforcement. Plan for ongoing activation. + +- Repeat the pairing across all channels (don't use different triggers in different contexts) +- Refresh creative while keeping the trigger-product link constant +- Measure trigger effectiveness over time (see Measurement section below) + +### Step 4: Defend Against Competitors + +Once you own a trigger, competitors may try to hijack it. + +- Monitor competitive messaging for trigger encroachment +- Double down on the trigger association if challenged +- Consider owning the trigger through trademark or distinctive execution + +## Competitive Triggers: Hijacking Competitor Moments + +One advanced trigger strategy is linking your product to a competitor's context — so that when people think of the competitor, they think of you. + +### How Competitive Triggers Work + +**The principle:** If your competitor's product or brand is a frequent environmental cue, you can link your product to it. This turns competitor visibility into your word-of-mouth. + +**Examples:** +- A challenger bank could tie its messaging to ATM fee receipts — every time a customer sees a fee, they think of the fee-free alternative +- A meditation app could tie to the stress of checking email — "Before you open your inbox, open [app]" +- A healthy snack brand could trigger when people see a vending machine — "Next time you see a vending machine, remember there's a better option" + +### Competitive Trigger Design + +| Step | Action | Example | +|------|--------|---------| +| 1. Identify competitor's high-frequency context | Where do people encounter the competitor's product? | People see Starbucks on every corner | +| 2. Find the pain point in that context | What frustration exists in that moment? | Long lines, expensive drinks | +| 3. Link your product to that pain point | Create messaging that triggers at that moment | "Tired of the line? Brew better at home with [brand]" | +| 4. Reinforce through proximity | Be visible near the competitor's context | Advertise near Starbucks locations | + +### Ethical Considerations for Competitive Triggers + +- Do not disparage the competitor directly +- Focus on the customer's need, not the competitor's weakness +- Ensure your product genuinely solves the triggered frustration +- Avoid confusion or misleading association + +## Trigger Timing and Context + +### Best Times for Triggers + +| Time Context | Why It Works | Application | +|-------------|-------------|-------------| +| **Morning routine** | Highly ritualized, same every day | Products tied to waking up, getting ready, commuting | +| **Meals** | 3x/day, social, conversation-rich | Food, beverage, health products | +| **Work transitions** | Multiple per day (arrive, break, leave) | Productivity tools, snacks, beverages | +| **Evening wind-down** | Daily, emotional, reflective | Entertainment, self-care, wellness | +| **Weekly markers** | Predictable, conversation-starting | "Monday motivation," "Friday feeling" | + +### Context-Dependent Triggers + +The same trigger can work differently in different contexts. Design for the specific context where you want to be top-of-mind. + +**Example:** "Rain" as a trigger: +- For a food delivery app: Rain = don't want to go outside = order in +- For a boot brand: Rain = need proper footwear = buy boots +- For a streaming service: Rain = cozy inside = time to watch +- For an umbrella brand: Rain = obvious product need + +The trigger is the same (rain), but the product link depends on the context you design around it. + +## Trigger Measurement + +### How to Know If Your Trigger Is Working + +| Metric | How to Measure | Target | +|--------|---------------|--------| +| **Aided recall** | Survey: "When you think of [trigger], what brands come to mind?" | Top 3 mention | +| **Conversation spikes** | Monitor social mentions around trigger events | Consistent spike within 1 hour of trigger | +| **Search correlation** | Track search volume against trigger frequency | Correlated search patterns | +| **Sales correlation** | Track sales against trigger occurrence | Sales lift on trigger days/times | +| **Spontaneous mention** | In user interviews, note unprompted trigger-product links | Users naturally pair the two | + +### Trigger Effectiveness Checklist + +- [ ] The trigger is encountered at least daily by the target audience +- [ ] The trigger-product link has been reinforced across at least 3 channels +- [ ] People can articulate the trigger-product connection unprompted +- [ ] Sales or engagement correlate with trigger frequency +- [ ] The trigger is not strongly owned by a competitor +- [ ] The trigger is present in the product's natural use context +- [ ] The trigger works offline, not just online + +## Exercises + +### Exercise 1: Habitat Mapping + +Spend one day observing your target customer's environment. List every environmental cue they encounter from waking up to going to bed. Rate each by frequency and relevance to your product. Select the top 3 trigger candidates. + +### Exercise 2: Trigger Audit + +For your current product or campaign, answer: What is the environmental trigger? How frequent is it? How strong is the association? If you can't identify a clear trigger, that's your biggest growth opportunity. + +### Exercise 3: The Friday Test + +Rebecca Black's "Friday" spikes every Friday. Does your product have a "Friday" — a regular environmental event that triggers thoughts of it? If not, design one. Pick a daily or weekly event and create a campaign that systematically links your product to it. + +### Exercise 4: Competitive Trigger Brainstorm + +List your top 3 competitors. For each, identify the most common context where people encounter their product. Design a trigger that redirects that moment toward your product. How would you execute it across advertising, content, and physical presence? diff --git a/.agents/skills/contagious/references/viral-content-patterns.md b/.agents/skills/contagious/references/viral-content-patterns.md new file mode 100644 index 00000000..bbcb3aa7 --- /dev/null +++ b/.agents/skills/contagious/references/viral-content-patterns.md @@ -0,0 +1,265 @@ +# Viral Content Patterns: Formats, Platforms, and Shareability + +Not all content is created equal when it comes to sharing. Certain content formats, structures, and platform-specific patterns dramatically increase the likelihood of content spreading. This reference provides a practical guide to designing content that is engineered for virality from the ground up. + +## Content Formats That Spread + +Different content formats have inherently different sharing properties. Understanding these properties allows you to choose the right vessel for your message. + +### The Shareability Hierarchy + +| Rank | Content Format | Shareability | Why It Spreads | Best Platform | +|------|---------------|-------------|---------------|---------------| +| 1 | **Interactive tools/quizzes** | Very high | Personalized results people want to display | Website, social media | +| 2 | **Lists/Listicles** | Very high | Scannable, specific promise, easy to reference | Blog, social media, email | +| 3 | **Infographics** | High | Visual, self-contained, easy to save | Pinterest, LinkedIn, Twitter | +| 4 | **Short-form video** | High | Entertaining, easy to consume, autoplay | TikTok, Instagram Reels, YouTube Shorts | +| 5 | **Controversies/Hot takes** | High | Triggers high-arousal emotions (anger, agreement) | Twitter, LinkedIn, Reddit | +| 6 | **How-to guides** | High | Immediately actionable, forward-worthy | Blog, YouTube, email | +| 7 | **Personal stories** | Medium-high | Relatable, emotional, identity-reinforcing | All platforms | +| 8 | **Data visualizations** | Medium-high | Novel insights, citation-worthy | LinkedIn, Twitter, blog | +| 9 | **Memes** | Medium-high | Humor, cultural relevance, low effort to share | Social media, messaging | +| 10 | **Long-form essays** | Medium | Deep value, but high effort to consume and share | Blog, email newsletter | +| 11 | **Podcasts** | Low-medium | High value but hard to share specific moments | Podcast platforms | +| 12 | **Whitepapers** | Low | High value but gated, formal, not conversation-ready | Email, LinkedIn | + +### Why Interactive Tools and Quizzes Win + +Interactive content generates 2x more shares than static content because: + +1. **Personalized output.** Every user gets a unique result, which gives them a unique thing to share. "I got [result]!" is inherently personal and identity-signaling. +2. **Completion investment.** After investing time to complete a quiz, people are motivated to share the result (sunk cost + reward). +3. **Social comparison.** "What did you get?" drives chain sharing as friends compare results. +4. **Curiosity gap.** Seeing someone else's result creates curiosity: "I need to find out mine." + +**Examples of high-performing interactive content:** +- BuzzFeed personality quizzes ("Which [character] are you?") +- Spotify Wrapped (personalized year-in-review) +- HubSpot Website Grader (free analysis with shareable score) +- Political compass tests ("Where do you fall on the spectrum?") +- Savings calculators ("How much are you overpaying?") + +### Designing Interactive Content for Maximum Sharing + +| Design Element | How to Optimize | Example | +|---------------|----------------|---------| +| **Result variety** | Create 5-12 distinct result types | Personality types, scores, categories | +| **Result shareability** | Pre-generate beautiful share cards for each result | Image with result + branded template | +| **Social comparison** | Show how the result compares to others | "You scored higher than 85% of people" | +| **One-click sharing** | Share button immediately after result reveal | Pre-filled social post with image | +| **Curiosity trigger** | Make results visible enough to provoke "What did you get?" | Shareable badges, profile additions | +| **Brand integration** | Brand must be visible on every shared result | Logo, URL, "Take the quiz at [brand]" | + +### Lists and Listicle Design + +Lists remain the most consistently shared content format across all platforms. Here is how to optimize them. + +**The Optimal List Structure:** + +| Element | Best Practice | Why | +|---------|------------|-----| +| **Number** | Odd numbers (7, 9, 11) slightly outperform even | Perceived as more authentic, less arbitrary | +| **Title specificity** | Specific beats vague | "7 Email Subject Lines That Doubled Our Open Rate" > "Email Tips" | +| **First item** | Make it the most surprising or valuable | Many people share after reading only #1 | +| **Last item** | Make it a strong closer or bonus | Rewards readers who made it to the end | +| **Length per item** | 50-200 words each | Enough depth to be useful, short enough to scan | +| **Visual breaks** | Include images, subheadings, or callouts | Prevents wall-of-text fatigue | + +### Controversy and Hot Takes + +Controversial content is highly shareable because it triggers high-arousal emotions (anger, outrage, passionate agreement). But it's also risky. + +**The Controversy Spectrum:** + +| Level | Type | Risk | Sharing Driver | Example | +|-------|------|------|---------------|---------| +| 1 - Safe | Challenging conventional wisdom | Low | "I never thought of it that way" | "Cold outreach is dead — here's what replaced it" | +| 2 - Moderate | Taking a professional stance | Medium | "I agree/disagree strongly" | "Remote work is more productive than office work" | +| 3 - Spicy | Naming industry problems | Medium-high | "Finally someone said it" | "Most SaaS marketing is manipulative" | +| 4 - Risky | Polarizing cultural positions | High | Strong tribalism | Cultural commentary tied to brand | +| 5 - Dangerous | Attacking groups or individuals | Very high | Outrage cycle | Personal attacks, punching down | + +**Recommendation:** Levels 1-3 generate high sharing with manageable risk. Level 4 requires careful judgment. Level 5 should be avoided — the backlash will outweigh the buzz. + +## Platform-Specific Sharing Patterns + +Each platform has distinct sharing mechanics and culture that affect what content spreads. + +### Platform Comparison Matrix + +| Platform | Primary Sharing Mechanic | Content That Spreads | Optimal Format | Sharing Motivation | +|----------|------------------------|---------------------|---------------|-------------------| +| **Twitter/X** | Retweet, Quote tweet | Hot takes, threads, breaking news, humor | Text + image, threads | Commentary, identity signaling | +| **LinkedIn** | Reshare, Comment | Professional insights, career stories, industry data | Text posts, carousels, articles | Professional identity, helpfulness | +| **Instagram** | Story share, DM forward | Visual content, aspirational lifestyle, reels | Images, Reels, Stories | Aesthetic identity, entertainment | +| **TikTok** | Duet, Stitch, Share | Entertaining video, tutorials, trends | Short video (15-60s) | Entertainment, participation | +| **Facebook** | Share, Tag | Family-relevant content, local news, nostalgia | Video, images, links | Connection, practical value | +| **Reddit** | Upvote, Crosspost | Deep analysis, humor, controversy, niche expertise | Text, images, links | Community contribution, expertise | +| **Email** | Forward | Useful articles, deals, important news | Newsletter, article link | Helpfulness, practical value | +| **WhatsApp/Messaging** | Forward, Group share | Deals, news, funny content, useful tips | Links, images, short video | Direct helpfulness to known people | + +### Platform-Specific Optimization + +**For Twitter/X:** +- Lead with the most provocative or surprising statement +- Use threads for depth (the first tweet is the hook) +- Include an image — tweets with images get 150% more retweets +- Time posts for maximum initial engagement (engagement begets more engagement) + +**For LinkedIn:** +- Open with a personal story or counter-intuitive insight +- Use line breaks generously (the mobile reading experience demands it) +- End with a question to drive comments (the algorithm rewards comments) +- Avoid self-promotion in the first 3 lines — lead with value + +**For Instagram:** +- Carousels get highest saves and shares (people swipe = algorithm boost) +- Educational Reels outperform entertainment in most niches +- Use Stories for raw, behind-the-scenes content — it feels more authentic +- The first frame of a Reel must hook in under 1 second + +**For TikTok:** +- Hook in the first 0.5 seconds — you're competing with a thumb scroll +- Use trending sounds and formats — participation in trends amplifies reach +- Teach something in under 60 seconds — educational content has highest share rate +- Encourage duets and stitches — they extend your content's life + +**For Email Forwards:** +- The subject line must work as a "forwarded to you because..." prompt +- Include one clear, useful takeaway per email +- Make the forwarded version self-contained (don't rely on context from previous emails) +- Add "Forward this to..." prompts explicitly + +## The Shareability Audit Framework + +Use this framework to evaluate any piece of content before publishing. + +### Pre-Publication Shareability Checklist + +| Dimension | Question | Score (0-10) | +|-----------|----------|-------------| +| **Headline hook** | Does the headline create a curiosity gap or promise specific value? | | +| **Emotional arousal** | Does the content evoke high-arousal emotion (awe, excitement, anger, humor)? | | +| **Social currency** | Does sharing this make the sharer look good (smart, informed, generous)? | | +| **Practical value** | Is there useful, actionable information someone would forward? | | +| **Format optimization** | Is the format chosen for maximum shareability on the target platform? | | +| **Visual appeal** | Is there a compelling visual (image, video, infographic) that travels with the share? | | +| **Brand integration** | Will the brand be visible/mentioned when the content is shared? | | +| **Conversation readiness** | Could someone describe this content in one sentence in a conversation? | | +| **Call to share** | Is there an explicit or implicit prompt to share? | | +| **Mobile optimization** | Does the content look and function well on mobile (where most sharing happens)? | | + +**Scoring:** +- **0-30:** Low shareability. Content will require paid distribution to reach audiences. +- **31-50:** Moderate shareability. Some organic spread with initial seeding. +- **51-70:** High shareability. Strong organic spread potential. +- **71-100:** Exceptional shareability. Content is engineered for maximum virality. + +## Viral Coefficient Basics + +The viral coefficient (K-factor) measures how many new users each existing user brings in through sharing. + +### Understanding K-Factor + +``` +K = i x c + +Where: +i = number of invitations/shares per user +c = conversion rate of each invitation/share +``` + +**Example:** +- Each user shares with 10 people (i = 10) +- 20% of those people sign up (c = 0.20) +- K = 10 x 0.20 = 2.0 + +### What K-Factor Means + +| K-Factor | Growth Pattern | Interpretation | +|----------|---------------|----------------| +| K < 1.0 | Decaying | Each cycle produces fewer users than the last. Growth slows and stops. | +| K = 1.0 | Stable | Each user brings exactly one new user. Linear growth. | +| K > 1.0 | Exponential | Each cycle produces more users than the last. True viral growth. | +| K > 2.0 | Explosive | Rapid exponential growth. Rare and usually unsustainable. | + +### Levers to Increase K-Factor + +| Lever | How to Improve | Target Improvement | +|-------|---------------|-------------------| +| **Increase invitations (i)** | Make sharing easier, more frequent, more rewarding | Add sharing prompts at peak moments | +| **Increase conversion (c)** | Improve landing page, reduce friction, add social proof | Optimize the referral landing experience | +| **Reduce cycle time** | Shorten the time between sign-up and first share | Front-load the "aha moment" | +| **Multi-channel sharing** | Enable sharing across email, social, messaging, in-person | Provide multiple share mechanisms | + +### Viral Cycle Time + +K-factor alone doesn't determine growth speed. The cycle time — how long it takes from a user signing up to their referrals signing up — is equally important. + +| Cycle Time | Even With K = 2.0 | Example | +|------------|-------------------|---------| +| 1 day | 1,024 users from 1 in 10 days | Messaging apps, social platforms | +| 1 week | 1,024 users from 1 in 10 weeks | Content platforms, SaaS tools | +| 1 month | 1,024 users from 1 in 10 months | Enterprise software, B2B tools | + +**The lesson:** Reducing cycle time is as valuable as increasing K-factor. Get users to their "share moment" as fast as possible. + +## Content Virality Patterns + +### Pattern 1: The Information Gap + +Create content that fills a gap people didn't know they had. + +**Structure:** "You think you know about X, but here's what you're missing." + +**Why it works:** Activates curiosity (high arousal) + provides practical value + makes the sharer look informed (social currency). + +### Pattern 2: The Definitive Resource + +Create the most comprehensive resource on a topic. + +**Structure:** "Everything you need to know about X in one place." + +**Why it works:** High practical value + people save and forward comprehensive resources + becomes a reference people return to and share. + +### Pattern 3: The Data Reveal + +Share original data or research that reveals something surprising. + +**Structure:** "We analyzed X and found Y — here's what it means." + +**Why it works:** Remarkable findings create social currency + data is citable (spreading through attribution) + original research is inherently rare and valuable. + +### Pattern 4: The Counter-Narrative + +Challenge a widely held belief with evidence. + +**Structure:** "Everyone says X, but the data shows Y." + +**Why it works:** High arousal (surprise, sometimes anger) + social currency (the sharer looks contrarian/informed) + triggers debate (comments and discussion amplify reach). + +### Pattern 5: The Personal Transformation + +Share a genuine personal or customer transformation story. + +**Structure:** "I went from X to Y by doing Z — here's exactly how." + +**Why it works:** Emotional arousal (inspiration) + practical value (the "how") + story (narrative vehicle) + social currency for the sharer ("I found this great story"). + +## Exercises + +### Exercise 1: Format Experiment + +Take one core message or insight. Create it in five different formats: a numbered list, a short video, an infographic, an interactive quiz, and a long-form essay. Publish all five on appropriate platforms. Compare sharing rates after 2 weeks. Which format won? Why? + +### Exercise 2: Platform-Native Redesign + +Take your best-performing piece of content. Redesign it natively for 3 different platforms (e.g., a Twitter thread, a LinkedIn carousel, and a TikTok video). Each version should feel native to the platform, not just reformatted. Compare performance. + +### Exercise 3: K-Factor Calculation + +Calculate your current K-factor. Identify the weakest lever (invitations per user or conversion rate). Design 3 interventions to improve that specific lever. Implement and measure over 30 days. + +### Exercise 4: Shareability Pre-Flight + +Before publishing your next 5 pieces of content, run each through the Shareability Audit Framework. Score each piece. For any scoring below 50, revise before publishing. After 5 pieces, compare: did higher-scoring content actually get more shares? diff --git a/.agents/skills/contagious/references/word-of-mouth.md b/.agents/skills/contagious/references/word-of-mouth.md new file mode 100644 index 00000000..e44ce5b3 --- /dev/null +++ b/.agents/skills/contagious/references/word-of-mouth.md @@ -0,0 +1,250 @@ +# Word-of-Mouth: The Dominant Channel Nobody Optimizes + +Word-of-mouth is the most powerful form of marketing. It drives 20-50% of all purchasing decisions and is up to 10 times more effective than traditional advertising. Yet most companies invest 90%+ of their marketing budget in channels other than WOM. Understanding how word-of-mouth actually works — especially the dominance of offline WOM — is essential to engineering contagious products and ideas. + +## The Offline Dominance: 93% vs. 7% + +One of the most surprising findings from Jonah Berger's research is the distribution of word-of-mouth: + +**93% of word-of-mouth happens offline.** Only 7% happens online. + +This finding runs counter to the prevailing obsession with social media, viral videos, and online sharing. While online WOM is visible and measurable, the vast majority of brand conversations happen face-to-face: over coffee, at dinner, in the car, at the office, on the phone. + +### Why Offline WOM Dominates + +| Factor | Offline WOM | Online WOM | +|--------|------------|-----------| +| **Frequency** | People have 16+ brand-related conversations per day offline | Average person shares brand content online a few times per week | +| **Trust** | Face-to-face recommendations carry highest trust | Online reviews and posts carry moderate trust | +| **Reach per instance** | Smaller (1-5 people per conversation) | Potentially larger (hundreds of followers) | +| **Depth** | Rich, contextual, back-and-forth dialogue | Often shallow (likes, retweets, brief comments) | +| **Retention** | Higher — personal recommendations are remembered | Lower — feeds move fast, posts are forgotten | +| **Measurability** | Very difficult to track | Relatively easy to track | + +### The Measurement Trap + +Because online WOM is easy to measure (likes, shares, retweets, comments), companies focus on optimizing it. Meanwhile, the much larger offline channel remains invisible and unoptimized. This creates a dangerous illusion: companies think they understand their WOM based on online metrics, but they're seeing only 7% of the picture. + +**What this means for strategy:** +- Don't optimize exclusively for online sharing +- Design products and messages that work in conversation, not just in feeds +- Test whether your value proposition can be easily articulated in a casual, face-to-face conversation +- The "social media strategy" is a subset of word-of-mouth strategy, not a substitute for it + +### Offline WOM Statistics + +| Statistic | Source/Context | +|-----------|---------------| +| People have ~16 word-of-mouth conversations per day | Berger's research | +| 93% of WOM is face-to-face or voice-to-voice | Keller Fay Group / Berger | +| WOM drives 20-50% of purchasing decisions | McKinsey | +| WOM is 10x more effective than traditional advertising | Research compilation | +| A personal recommendation is 2-10x more trusted than a brand message | Nielsen | +| Offline WOM generates 5x the sales of paid advertising | Berger / various studies | + +## Why Offline WOM Matters More + +Beyond the 93% volume advantage, offline WOM has qualitative advantages that make it more impactful per interaction. + +### Trust and Persuasion + +When a friend tells you face-to-face that they love a product, several trust mechanisms activate: + +1. **Social accountability** — they're putting their reputation on the line in person +2. **Non-verbal cues** — you can see their genuine enthusiasm (or lack thereof) +3. **Contextual relevance** — they're telling you because they know your specific situation +4. **Dialogue** — you can ask questions, get clarification, understand nuance +5. **Relationship depth** — recommendations from close ties carry more weight + +Online recommendations lack most of these. A tweet saying "Love this product!" carries a fraction of the persuasive weight of a friend looking you in the eye and saying the same thing. + +### The Conversation Funnel + +Offline WOM follows a natural conversation funnel: + +``` +Environmental Trigger (cue in the environment) + ↓ +Top-of-Mind Recall (product comes to mind) + ↓ +Conversation Opportunity (social context allows sharing) + ↓ +Articulation (person describes the product/experience) + ↓ +Social Response (listener asks questions, shows interest) + ↓ +Action (listener investigates, tries, or purchases) +``` + +**The key bottleneck:** Articulation. If someone can't easily describe your product in a sentence or two, the conversation stalls. Your value proposition must be conversationally simple. + +## Conversation Triggers: Designing for Talk + +A conversation trigger is something about your product, brand, or experience that naturally comes up in everyday conversation. It's different from an environmental trigger (which reminds someone of the product) — it's the thing that gives someone a reason to bring it up. + +### Types of Conversation Triggers + +| Trigger Type | Mechanism | Example | Conversation Starter | +|-------------|-----------|---------|---------------------| +| **Remarkable experience** | Something unusual happened during product use | $100 cheesesteak at Barclay Prime | "You won't believe what I had for lunch" | +| **Useful discovery** | Found something genuinely helpful | A coupon app that saved $50 on groceries | "You should try this app — I saved $50" | +| **Identity expression** | Product says something about who they are | Driving a Tesla | "I got the new Tesla — let me tell you about it" | +| **Problem-solution** | Product solved a specific pain point | Password manager after a security scare | "After I got hacked, I found this tool..." | +| **Social experience** | Shared experience with others | Trying a new restaurant together | "We went to this amazing place..." | +| **Status change** | Achieved something through the product | Completed a challenging course | "I just finished [program] — it was intense" | + +### Designing Conversation Triggers + +**Step 1: Map the conversation contexts.** When and where does your target customer have conversations where your product category could naturally come up? + +| Context | Who They Talk To | Topics That Arise | +|---------|-----------------|-------------------| +| Morning commute (carpool/transit) | Colleagues, strangers | Work tools, productivity, frustrations | +| Lunch with friends | Close friends | Life updates, purchases, experiences | +| Family dinner | Family members | Health, money, home, kids | +| Weekend social events | Mixed social group | Entertainment, travel, new discoveries | +| Work meetings | Professional peers | Tools, strategies, industry trends | + +**Step 2: Create a talking point.** For each context, what could someone say about your product that would feel natural and interesting? + +**Step 3: Make it easy to articulate.** The talking point should be expressible in one sentence: +- "I found this app that [remarkable benefit]" +- "Did you know [surprising fact about the product]?" +- "I tried [product] and [specific impressive result]" + +**Step 4: Provide proof.** Give users something to show during the conversation — a before/after photo, a result screenshot, a physical artifact — that makes the recommendation tangible. + +## Word-of-Mouth Measurement + +Measuring WOM is challenging, especially offline. Here are approaches for both channels. + +### Online WOM Measurement + +| Metric | How to Measure | What It Tells You | +|--------|---------------|-------------------| +| **Social mentions** | Brand monitoring tools (Mention, Brandwatch) | Volume of online conversation | +| **Share rate** | Shares per impression on content | Content shareability | +| **Net Promoter Score (NPS)** | Survey: "Would you recommend us?" (0-10) | Likelihood of recommendation | +| **Referral traffic** | Analytics tracking referral sources | Who's sending people your way | +| **Earned media** | PR monitoring, press mentions | Third-party brand discussion | +| **Review volume** | Review platforms (G2, Yelp, Amazon) | Quantity of public opinions | + +### Offline WOM Measurement + +| Method | How It Works | Limitation | +|--------|-------------|-----------| +| **"How did you hear about us?"** | Ask new customers directly | Recall bias — people forget or misattribute | +| **Conversation diaries** | Participants log brand conversations for a week | Effort-intensive, sample bias | +| **Referral codes** | Track who referred whom | Only captures deliberate referrals, misses casual mentions | +| **Qualitative interviews** | In-depth conversations with customers about sharing behavior | Small sample, not scalable | +| **Promo code tracking** | Unique codes per referrer | Only tracks when a code is used | +| **Brand lift studies** | Survey awareness in target markets over time | Doesn't isolate WOM from other channels | + +### The WOM Scorecard + +| Metric | Current | Target | Gap | +|--------|---------|--------|-----| +| NPS score | ___ | 50+ | ___ | +| Share rate (content) | ___ | 5%+ | ___ | +| Referral as % of new customers | ___ | 30%+ | ___ | +| Organic social mentions/month | ___ | ___ | ___ | +| Average rating on review sites | ___ | 4.5+ | ___ | +| "How did you hear about us?" = WOM % | ___ | 40%+ | ___ | + +## The Word-of-Mouth Audit + +A comprehensive audit to evaluate your product's WOM health across both channels. + +### Part 1: Product-Level WOM Drivers + +| Question | Answer | Score (0-10) | +|----------|--------|-------------| +| Is there something remarkable about the product that people would mention in conversation? | | | +| Is the product linked to a frequent environmental trigger? | | | +| Does the product evoke high-arousal emotion during or after use? | | | +| Is product usage visible to others? | | | +| Is there practical value that users would want to share with specific people? | | | +| Is the product embedded in a retellable story? | | | + +### Part 2: Articulation Readiness + +| Question | Answer | Score (0-10) | +|----------|--------|-------------| +| Can a user describe the product's value in one sentence? | | | +| Does the description sound natural in conversation (not marketing-speak)? | | | +| Is there a specific "Did you know...?" fact about the product? | | | +| Can a user show proof during conversation (result, photo, artifact)? | | | +| Is the product name easy to say and remember? | | | + +### Part 3: Channel Health + +| Channel | Current Status | Opportunity | +|---------|---------------|-------------| +| Face-to-face conversations | | | +| Phone/voice conversations | | | +| Text/messaging | | | +| Social media | | | +| Email forwards | | | +| Online reviews | | | +| Community forums | | | + +### Audit Scoring + +- **0-30:** WOM-poor. Product relies on paid channels. Major opportunity to engineer sharing. +- **31-50:** WOM-moderate. Some organic discussion. Significant room to amplify. +- **51-70:** WOM-healthy. Regular organic conversations driving growth. Optimize and sustain. +- **71-100:** WOM-dominant. Product primarily grows through word-of-mouth. Focus on protecting and scaling. + +## Strategies to Amplify Offline WOM + +Since 93% of WOM is offline, here are strategies specifically designed to increase face-to-face brand conversations. + +### Strategy 1: Create Tangible Conversation Starters + +Give users physical artifacts that prompt questions from others. + +| Artifact | How It Works | Example | +|----------|-------------|---------| +| Distinctive packaging | Seen by others when carried or displayed | Apple's white bags, Tiffany's blue box | +| Branded accessories | Worn or used in public | Branded water bottles, laptop stickers | +| Result artifacts | Proof of outcomes others can see | Fitness transformation photos, before/after | +| Gift-worthy outputs | Things users give to others | Shareable reports, printed certificates | + +### Strategy 2: Engineer Remarkable Moments + +Create peak experiences during product use that become stories people tell later. + +| Moment Type | Design Principle | Example | +|-------------|-----------------|---------| +| Surprise delight | Unexpected positive experience | Handwritten thank-you note in package | +| Achievement milestone | Celebration of user accomplishment | Personalized congratulations at milestones | +| Social experience | Shared moment with others | Group challenges, team features | +| Transformation reveal | Dramatic before/after moment | Progress photos in fitness apps | + +### Strategy 3: Simplify the Vocabulary + +If people can't easily say what your product does, they won't talk about it. Create simple, conversational language for your value proposition. + +| Complex Description | Conversational Version | +|--------------------|----------------------| +| "AI-powered customer relationship management platform" | "It keeps track of all your customers for you" | +| "End-to-end DevOps automation suite" | "It handles all the boring deployment stuff automatically" | +| "Omnichannel marketing attribution solution" | "It tells you which marketing is actually working" | + +## Exercises + +### Exercise 1: The Dinner Party Test + +Describe your product as if recommending it to a friend at a dinner party. Record yourself. Listen back. Does it sound natural? Would someone actually say that? If it sounds like marketing copy, simplify until it sounds like human speech. + +### Exercise 2: WOM Channel Map + +For one week, track every time you mention a brand (or hear someone else mention one) in conversation. Note the channel (face-to-face, phone, text, social), the trigger (what prompted it), and the brand. At the end of the week, analyze: What percentage was offline? What triggers were most common? + +### Exercise 3: Articulation Workshop + +Gather 10 customers. Ask each to describe your product to someone who has never heard of it. Record the descriptions. Analyze: What words do they use? What do they emphasize? What do they struggle to explain? Use the most natural, effective descriptions in your marketing. + +### Exercise 4: Offline WOM Boost + +Design three specific interventions to increase offline word-of-mouth: one tangible artifact, one remarkable moment, and one vocabulary simplification. Implement all three over 30 days and measure referral rates before and after. diff --git a/.agents/skills/continuous-discovery/SKILL.md b/.agents/skills/continuous-discovery/SKILL.md new file mode 100644 index 00000000..f945139c --- /dev/null +++ b/.agents/skills/continuous-discovery/SKILL.md @@ -0,0 +1,202 @@ +--- +name: continuous-discovery +description: 'Build a weekly cadence of customer touchpoints using Opportunity Solution Trees, assumption mapping, and interview snapshots. Use when the user mentions "continuous discovery", "opportunity solution tree", "weekly interviews", "assumption testing", "discovery habits", "product trio", "outcome-based roadmap", "how do I talk to customers regularly", "we keep building things nobody uses", or "connect research to the roadmap". Also trigger when setting up regular customer feedback loops, prioritizing which experiments to run, or tying discovery insights to delivery work. Covers experience mapping, co-creation, and prioritizing opportunities. For interview technique, see mom-test. For team structure, see inspired-product.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Continuous Discovery Habits Framework + +Framework for building a sustainable weekly practice of customer discovery that keeps product teams progressing toward desired outcomes. Discovery is not a phase before development — it is embedded in the ongoing rhythm of product work so every decision is informed by fresh evidence. + +## Core Principle + +**Good product discovery requires a continuous cadence, not a one-time event.** Teams that talk to customers every week, map opportunities visually, and test assumptions before building consistently outperform teams that rely on intuition, stakeholder opinions, or quarterly research cycles. The benchmark: at least one customer touchpoint per week, every week, by the product trio (product manager, designer, engineer). + +## Scoring + +**Goal: 10/10.** Score a discovery practice by the seven Quick Diagnostic rows below — start at 3, add 1 point per row answered "yes" (max 10). Bands: **9-10** = weekly cadence, a living Opportunity Solution Tree, systematic assumption testing, and every shipped feature traceable to a customer opportunity; **5-6** = some discovery happening but ad hoc, PM-only, or disconnected from delivery; **≤3** = intuition- and stakeholder-driven with no regular customer contact. Report the current score, the failing rows, and the specific fix for each. + +## Framework + +### 1. Opportunity Solution Trees + +**Core concept:** An Opportunity Solution Tree (OST) visually connects a desired outcome (top) to customer opportunities (middle) to potential solutions and experiments (bottom), making implicit product thinking explicit and shared. + +**Why it works:** Most teams jump from business outcome straight to solutions, skipping the customer need entirely; the OST forces understanding of the opportunity space first, preventing features nobody wants. + +**Key insights:** +- Four layers: Outcome > Opportunities > Solutions > Experiments +- Opportunities are customer needs, pain points, and desires — framed from the customer's perspective +- The tree is a living artifact, updated weekly as the team learns +- Break large opportunities into smaller sub-opportunities to make them actionable +- Pursue multiple opportunities simultaneously — don't bet everything on one + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Quarterly planning | Map the opportunity space before committing to features | "Increase trial-to-paid conversion" → discover why users don't convert | +| Feature prioritization | Compare solutions across opportunities for the highest-leverage bet | Three solutions for "can't find content" vs. two for "confusing onboarding" | +| Stakeholder alignment | Use the tree as the shared strategy visual | Walk leadership through why you chose opportunity X over Y | + +**Ethical boundary:** Never cherry-pick opportunities to justify a predetermined solution — the tree must reflect needs discovered through research. + +See [references/opportunity-trees.md](references/opportunity-trees.md) when building or auditing a tree — adds the 4-layer diagram, good-vs-poor outcome tables, solution-generation techniques, a weekly update rhythm, healthy/dying-tree signals, two worked examples, and four anti-patterns. + +### 2. Experience Mapping + +**Core concept:** Current-state experience maps capture how customers accomplish a goal today, step by step, revealing pain points that become opportunities on the tree. + +**Why it works:** Teams assume they understand the customer's current experience; mapping it from interview data exposes gaps, workarounds, and emotions invisible from inside the building. + +**Key insights:** +- Map the current state, not a future ideal — understand reality first +- Include actions, thoughts, and feelings at each step +- Build collaboratively with the full trio, sourced from interview data, not assumptions +- Experience maps cover the customer's full experience; journey maps cover only your product's touchpoints +- Pain points and high-emotion moments become OST opportunities + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| New problem space | Map end-to-end before designing | How a small business owner handles invoicing, from creation to chasing payment | +| Churn analysis | Map churned users' experience to find failure points | Users abandon onboarding at step 4 — they lack data they need on hand | +| Cross-functional alignment | Build the map together | A three-hour collaborative session produces one shared reference artifact | + +See [references/experience-mapping.md](references/experience-mapping.md) when mapping a new problem space or churn flow — adds the current-state map template, the experience-vs-journey-map distinction, and the collaborative mapping exercise. + +### 3. Interview Snapshots + +**Core concept:** Story-based interviews capture specific past experiences (not opinions or predictions), and each interview is synthesized into a one-page snapshot the whole team can absorb and reference. + +**Why it works:** Customers are poor predictors of their own future behavior; grounding insights in real past events reveals what they actually did and felt, and snapshots turn each interview into a growing library of evidence. + +**Key insights:** +- Ask about specific past behavior: "Tell me about the last time you..." not "Would you use...?" +- Each snapshot captures the story, key quotes, opportunities identified, and an identifier +- The trio interviews together so insights aren't lost in translation +- Automate recruitment so interviews happen weekly without heroic effort +- Patterns across snapshots reveal opportunities; single interviews only reveal stories + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Weekly cadence | Standing 30-minute interview slots | Recruit via in-app prompt; rotate who leads | +| Opportunity discovery | Extract needs from stories onto the OST | A data-export workaround becomes an opportunity node | +| Team alignment | Share snapshots visibly | A board where snapshots accumulate and patterns emerge | + +**Ethical boundary:** Never lead participants toward conclusions — ask open-ended questions about past behavior and let the story reveal what matters. + +See [references/interview-snapshots.md](references/interview-snapshots.md) when running interviews or setting up recruitment — adds story-based interview structure, the one-page snapshot format, synthesis across snapshots, and how to automate weekly recruitment. + +### 4. Assumption Testing + +**Core concept:** Before building, identify the assumptions a solution depends on, map them by importance and evidence, then run small fast tests on the riskiest ones first. + +**Why it works:** Every solution sits on a stack of desirability, viability, feasibility, and usability assumptions; most teams test none — or only the easy ones — and invest months in solutions built on false premises. + +**Key insights:** +- Four assumption types: desirability (do they want it?), viability (can we sustain it?), feasibility (can we build it?), usability (can they use it?) +- Map on a 2x2: importance vs. evidence; high-importance, low-evidence = leap-of-faith assumptions to test first +- Design the smallest test that generates evidence: one-question surveys, painted-door tests, prototypes, data mining +- Set success criteria before running the test: "validated if..." +- One assumption test should take days, not weeks + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Before building | Test the riskiest assumption of the top candidates | "Users will share reports with their manager" → painted-door button before building sharing | +| Comparing solutions | Test each candidate's riskiest assumption to eliminate weak options fast | A's riskiest assumption fails, B's passes → pursue B | +| De-risking a roadmap | Find untested assumptions hiding in committed features | Q3 feature assumes users want real-time notifications — no evidence yet | + +**Ethical boundary:** Never deceive participants — painted-door tests should say the feature is coming soon, not fake functionality without disclosure. + +See [references/assumption-mapping.md](references/assumption-mapping.md) when designing a test for a risky assumption — adds the four assumption types in depth, the importance-vs-evidence 2x2, the test-design menu, and how to set success criteria for leap-of-faith assumptions. + +### 5. Prioritizing Opportunities + +**Core concept:** Compare opportunities against each other — not in isolation — using opportunity size, market, company, and customer factors to find the highest-leverage bets. + +**Why it works:** Teams default to the loudest stakeholder, recency bias, or gut feel; structured head-to-head comparison forces explicit tradeoff discussions and surfaces disagreements before implementation. + +**Key insights:** +- Relative comparison beats independent scoring +- Size opportunities by how many customers are affected, how often, how severely +- Weigh strategy alignment, team capability, and existing evidence +- Make a good-enough decision quickly, then learn fast — avoid analysis paralysis +- Revisit the ranking as new evidence arrives + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Quarterly planning | Rank the top 5-7 OST opportunities | "Can't find content" vs. "no real-time collaboration" via structured criteria | +| Sprint planning | Pick the opportunity with the strongest current evidence | Choose where you have the most interview data and a testable solution | +| Portfolio decisions | Spread effort by risk and impact | 60% high-confidence, 30% medium, 10% exploratory | + +See [references/prioritization-methods.md](references/prioritization-methods.md) when ranking your top opportunities — adds the opportunity-sizing method, the compare-and-contrast technique, how to weigh data, and how to avoid analysis paralysis. + +### 6. Building the Habit + +**Core concept:** Continuous discovery only works as a sustainable weekly habit for the trio — automate recruitment, create lightweight rituals, and embed discovery into the existing workflow rather than treating it as extra work. + +**Why it works:** Discovery that depends on "finding time" loses to delivery pressure every week; structural support (automated recruitment, standing slots, shared artifacts) removes the per-week decision so the habit survives and compounds. + +**Key insights:** +- The whole trio participates — not just the PM +- Automate recruitment: in-app intercepts, advisory panels, scheduling tools that fill slots +- Block recurring calendar time — discovery that depends on "finding time" never happens +- Fill in the snapshot immediately after the interview, not days later +- Start with one interview per week; connect insights to the OST and from there into sprint planning + +**Product applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Team kickoff | Establish cadence in week one | Automated recruitment, blocked Thursday slot, snapshot template | +| Scaling discovery | Grow from one to three interviews weekly | Add a churned-user slot and a prospect slot | +| Manager support | Leaders protect time and ask for evidence | "What did you learn from interviews this week?" in every 1:1 | + +**Ethical boundary:** Respect participant time — keep interviews to 30 minutes, compensate fairly, and never disguise a sales pitch as discovery. + +See [references/case-studies.md](references/case-studies.md) when adapting the habit to your context — worked walkthroughs of continuous discovery in B2B SaaS, consumer mobile, platform, and growth teams. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Discovery as a phase before development | Insights go stale; team builds on old assumptions | Embed discovery into every week alongside delivery | +| Only the PM talks to customers | Designer and engineer lose context in translation | The full trio interviews together | +| Jumping from outcome to solutions | Skips the opportunity space | Build an OST to make it explicit | +| Asking customers what they want | You get feature requests, not needs | Story-based interviewing: "Tell me about the last time..." | +| Testing easy assumptions, not risky ones | False confidence; the fatal assumption goes untested | Map by importance and evidence; test high-risk first | +| Scoring opportunities in isolation | Everything looks important | Compare head-to-head with structured criteria | +| Interview burst, then stopping | No compounding learning | Automate recruitment; block recurring time | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| One customer conversation per week minimum? | Decisions lack fresh evidence | Automate recruitment; block a weekly slot | +| A living Opportunity Solution Tree? | Strategy is implicit and unshared | Build an OST from your outcome and interview data | +| Full trio in interviews? | Insights filtered through one person | Invite the designer and engineer to the next one | +| Testing assumptions before building? | Betting on untested premises | Map your next feature's assumptions; test the riskiest | +| Can you trace a shipped feature to a customer opportunity? | Delivery disconnected from discovery | Link backlog items to OST opportunities | +| Interview snapshots visible to the whole team? | Knowledge trapped in one head | Shared snapshot board, filled after each interview | +| Comparing opportunities, not just listing them? | Prioritization by opinion | Run a structured comparison on your top 5 | + +## Further Reading + +Based on the continuous discovery framework developed by Teresa Torres: + +- [*"Continuous Discovery Habits: Discover Products that Create Customer Value and Business Value"*](https://www.amazon.com/Continuous-Discovery-Habits-Discover-Products/dp/1736633309?tag=wondelai00-20) by Teresa Torres + +## About the Author + +**Teresa Torres** is an author, speaker, and coach who has helped hundreds of product teams — from startups to Capital One and Calendly — adopt continuous discovery. She created the Opportunity Solution Tree, writes the widely read Product Talk blog, and distilled her coaching practice into *Continuous Discovery Habits*. diff --git a/.agents/skills/continuous-discovery/references/assumption-mapping.md b/.agents/skills/continuous-discovery/references/assumption-mapping.md new file mode 100644 index 00000000..569a54a4 --- /dev/null +++ b/.agents/skills/continuous-discovery/references/assumption-mapping.md @@ -0,0 +1,249 @@ +# Assumption Mapping + +A detailed guide to identifying, categorizing, prioritizing, and testing the assumptions that underlie product decisions, so teams invest in building only what evidence supports. + +## Why Assumptions Matter + +Every product decision rests on a stack of assumptions. When a team says "let's build feature X to solve opportunity Y," they are implicitly assuming: +- Customers actually have this need (desirability) +- Customers can figure out how to use it (usability) +- We can build it with acceptable effort (feasibility) +- The business can sustain it (viability) + +Most teams never make these assumptions explicit. They build first and discover their assumptions were wrong after investing weeks or months. Assumption mapping inverts this: make assumptions explicit, identify the riskiest ones, and test them cheaply before committing resources. + +## Types of Assumptions + +### Desirability Assumptions + +**Question:** Do customers want this? Will they choose to use it? + +These are the most common and most dangerous assumptions because teams often believe their own enthusiasm is evidence of customer demand. + +| Assumption Pattern | Example | Test Approach | +|-------------------|---------|---------------| +| "Customers have this problem" | "Users struggle to find relevant content" | Interview stories confirming the struggle | +| "Customers want this solution" | "Users would use AI-generated summaries" | Painted-door test measuring clicks | +| "This is important enough to switch for" | "Users would leave competitor X for this" | Pre-order or commitment test | +| "Customers will adopt this behavior" | "Users will share reports with their team" | Prototype test measuring sharing behavior | + +### Viability Assumptions + +**Question:** Does this work for our business? Can we sustain it? + +| Assumption Pattern | Example | Test Approach | +|-------------------|---------|---------------| +| "Customers will pay for this" | "Users will upgrade from free to paid for this feature" | Pricing page test, pre-sale offers | +| "This won't cannibalize existing revenue" | "Adding a cheaper tier won't downgrade existing customers" | Conjoint analysis, segment analysis | +| "We can acquire customers profitably" | "CAC for this segment will be under $50" | Small-scale ad campaign test | +| "This fits our brand and strategy" | "Enterprise customers won't see this as too consumer-y" | Customer advisory board feedback | + +### Feasibility Assumptions + +**Question:** Can we build this? Do we have the capability? + +| Assumption Pattern | Example | Test Approach | +|-------------------|---------|---------------| +| "The technology can do this" | "Our ML model can achieve 90% accuracy" | Technical spike or prototype | +| "We can build this in time" | "We can ship this in the current quarter" | Timeboxed prototype | +| "Third-party dependencies will work" | "The API we depend on can handle our volume" | Load test against the API | +| "Our data is sufficient" | "We have enough training data for the model" | Data audit and small-scale test | + +### Usability Assumptions + +**Question:** Can customers figure out how to use this? Will they succeed? + +| Assumption Pattern | Example | Test Approach | +|-------------------|---------|---------------| +| "Users will find this feature" | "Users will notice the new button in the toolbar" | Unmoderated usability test | +| "Users will understand the concept" | "Users will understand what 'workspaces' means" | Five-second test or concept test | +| "Users can complete the workflow" | "Users can set up an automation in under 5 minutes" | Task-based usability test | +| "The mental model matches" | "Users think of this as a 'project,' not a 'folder'" | Card sort or tree test | + +## The Assumption Mapping Technique + +### Step 1: Generate Assumptions + +For each solution the team is considering, brainstorm all the assumptions that must be true for it to succeed. Use the four categories as prompts: + +**Facilitator prompts:** +- "For this solution to work, what must be true about what customers want?" (desirability) +- "For this to be viable, what must be true about our business model?" (viability) +- "For us to build this, what must be true about our technology and team?" (feasibility) +- "For customers to succeed with this, what must be true about the experience?" (usability) + +**Tips for generating assumptions:** +- Write each assumption as a statement that could be true or false: "Users will share reports at least once per week" +- Be specific: "Users will pay" is too vague; "Users will pay $20/month for this feature" is testable +- Include implicit assumptions the team takes for granted -- these are often the most dangerous +- Aim for 10-20 assumptions per solution + +### Step 2: Map Assumptions on the 2x2 + +Plot each assumption on a two-axis grid: + +``` + HIGH IMPORTANCE + (fatal if wrong) + │ + │ + ┌─────────────────┼─────────────────┐ + │ │ │ + │ TEST THESE │ WATCH THESE │ + │ FIRST │ (probably OK) │ + │ │ │ +LOW ────┼─────────────────┼─────────────────┼──── HIGH +EVIDENCE│ │ │ EVIDENCE + │ TEST THESE │ SAFE TO │ + │ SECOND │ ASSUME │ + │ │ │ + │ │ │ + └─────────────────┼─────────────────┘ + │ + LOW IMPORTANCE + (survivable if wrong) +``` + +**Importance (vertical axis):** How critical is this assumption? If it's wrong, does the whole solution fail (high), or is it a minor setback (low)? + +**Evidence (horizontal axis):** How much do we already know? Do we have strong evidence from interviews, data, or tests (high), or is this pure speculation (low)? + +### Step 3: Identify Leap-of-Faith Assumptions + +The assumptions in the top-left quadrant -- high importance, low evidence -- are your **leap-of-faith assumptions**. These are the ones that could kill your solution if wrong, and you have little or no evidence to support them. + +**Rule:** Never build a solution without first testing its leap-of-faith assumptions. + +### Step 4: Prioritize Testing Order + +Test in this order: +1. **High importance, low evidence** (leap-of-faith) -- test first, these are fatal unknowns +2. **Low importance, low evidence** -- test second if easy, or defer +3. **High importance, high evidence** -- monitor but don't spend testing effort +4. **Low importance, high evidence** -- safe to assume; revisit only if context changes + +## Designing Assumption Tests + +### Principles of Good Tests + +| Principle | What It Means | Anti-Pattern | +|-----------|---------------|-------------| +| **Fast** | Complete in days, not weeks | 3-month A/B test for a single assumption | +| **Cheap** | Minimal resource investment | Building the full feature to "test" it | +| **Specific** | Tests one assumption at a time | Test that conflates desirability with usability | +| **Falsifiable** | Could produce a negative result | Test designed to only confirm what you hope | +| **Pre-committed criteria** | Success/failure defined before the test | "We'll know it when we see it" | + +### Test Types by Assumption Category + +#### Desirability Tests + +| Test Type | Description | When to Use | Example | +|-----------|-------------|-------------|---------| +| **Painted door** | Add a button/link for a feature that doesn't exist yet; measure clicks | Early signal of interest | "Export to PDF" button that shows "Coming soon" and counts clicks | +| **One-question survey** | Ask one targeted question in-app to a sample of users | Quick pulse on a specific need | "How often do you need to share reports with people outside your team?" | +| **Fake feature** | Describe a feature in marketing material and measure interest | Before building anything | Landing page describing the feature; measure signup intent | +| **Concierge test** | Manually deliver the value to a small group | Validate the value before automating | Manually create the reports users would get from the feature | + +#### Viability Tests + +| Test Type | Description | When to Use | Example | +|-----------|-------------|-------------|---------| +| **Pricing page test** | Show different pricing options and measure selection | Before setting prices | A/B test with $10/mo vs. $20/mo tier including the feature | +| **Pre-sale** | Offer early access at a discount; measure commitment | Before building | "Get lifetime access for $99 if you commit now" | +| **Unit economics model** | Build a spreadsheet model with conservative estimates | When cost structure is uncertain | Model the cost per user of running the ML model at scale | + +#### Feasibility Tests + +| Test Type | Description | When to Use | Example | +|-----------|-------------|-------------|---------| +| **Technical spike** | Timeboxed engineering exploration (1-3 days) | When technical risk is high | Can we get API response times under 200ms for this query? | +| **Prototype** | Working but unpolished implementation | When the approach is novel | Build a rough version of the algorithm and test accuracy | +| **Third-party evaluation** | Test external dependencies | When relying on external services | Can the vendor's API handle our expected request volume? | + +#### Usability Tests + +| Test Type | Description | When to Use | Example | +|-----------|-------------|-------------|---------| +| **Five-second test** | Show a design for 5 seconds; ask what they noticed | Testing discoverability | "Where would you click to export your report?" | +| **Unmoderated test** | Give users a task with a prototype; observe via recording | Testing task completion | "Using this prototype, create a weekly report" | +| **Concept test** | Show a description/sketch and ask for comprehension | Testing mental model | "Based on this description, what do you think 'workspace' means?" | +| **Wizard of Oz** | Users interact with what seems real but is manually operated | Testing the full experience | Users submit a request; team manually fulfills it behind the scenes | + +## Setting Success Criteria + +**Before running any test**, define what success and failure look like. This prevents post-hoc rationalization. + +### Formula for Success Criteria + +"We'll consider this assumption **validated** if [measurable outcome] reaches [threshold] within [timeframe]." + +**Examples:** +- "We'll consider 'users want PDF export' validated if at least 15% of active users click the painted-door button within one week." +- "We'll consider 'users can complete setup in under 5 minutes' validated if 80% of test participants finish the task without help." +- "We'll consider 'users will pay $20/month' validated if at least 5% of free users shown the upgrade page initiate checkout." + +### Choosing Thresholds + +| Factor | Lower Threshold | Higher Threshold | +|--------|----------------|-----------------| +| High-cost solution | Need stronger signal before investing | 20%+ engagement | +| Low-cost solution | Moderate signal is sufficient | 10%+ engagement | +| Many alternatives exist | Need to be clearly better | Above baseline by 2x | +| No alternatives exist | Lower bar for "good enough" | Any measurable engagement | + +## Assumption Testing in Practice + +### Weekly Rhythm + +| Day | Activity | Time | +|-----|----------|------| +| Monday | Review last week's test results; update assumption map | 30 min | +| Monday | Identify next assumption to test; design the test | 30 min | +| Tue-Thu | Run the test | Varies (often passive) | +| Friday | Collect results; decide: validated, invalidated, or inconclusive | 30 min | + +### When Tests Are Inconclusive + +Not every test produces a clear signal. When results are ambiguous: + +1. **Check the test design:** Was the sample large enough? Was the test specific enough? +2. **Refine and retest:** Adjust the test to be more targeted +3. **Lower the stakes:** If you can't get a clear signal, is there a way to build a smaller version that lets you learn in production? +4. **Time-box the uncertainty:** "If we can't validate this in two more weeks of testing, we'll move to a different solution" + +### Documenting Test Results + +For each assumption test, record: +- **Assumption tested:** The specific statement +- **Test type:** What you did +- **Success criteria:** What you defined upfront +- **Results:** What actually happened +- **Decision:** Validated, invalidated, or inconclusive +- **Next step:** What changes based on this result + +This creates an audit trail of evidence that supports decision-making and helps new team members understand why choices were made. + +## Leap-of-Faith Assumptions: Deep Dive + +Leap-of-faith assumptions are the untested beliefs that, if wrong, make the entire solution pointless. They deserve special attention. + +### How to Identify Them + +Ask the team: "If we could only test one thing before building, what would tell us the most about whether this will work?" + +Common leap-of-faith patterns: +- **"They have this problem"** -- the need hasn't been validated through interviews +- **"They'll change their behavior"** -- the solution requires users to adopt a new habit +- **"They'll pay for this"** -- no evidence of willingness to pay +- **"This will work technically"** -- novel technology that hasn't been proven at this scale + +### The Cost of Skipping + +| Scenario | If You Test First | If You Skip Testing | +|----------|-------------------|---------------------| +| Assumption is true | Confidence to invest; 1-2 weeks of testing | Same confidence but weeks later | +| Assumption is false | Pivot early; save weeks/months of build time | Discover after full build; waste entire investment | +| Assumption is partially true | Refine the approach; build the right version | Build the wrong version; costly rework | + +The asymmetry is clear: the cost of testing is always small compared to the cost of building on a false assumption. diff --git a/.agents/skills/continuous-discovery/references/case-studies.md b/.agents/skills/continuous-discovery/references/case-studies.md new file mode 100644 index 00000000..97f2f345 --- /dev/null +++ b/.agents/skills/continuous-discovery/references/case-studies.md @@ -0,0 +1,307 @@ +# Case Studies: Continuous Discovery in Practice + +Four realistic scenarios showing how product teams apply continuous discovery habits across different contexts. Each case study follows a team from establishing the practice through making evidence-based decisions. + +## Table of Contents +1. [Case Study 1: B2B SaaS -- Project Management Tool](#case-study-1-b2b-saas-project-management-tool) +2. [Case Study 2: Consumer Mobile -- Fitness App](#case-study-2-consumer-mobile-fitness-app) +3. [Case Study 3: Platform Team -- Internal Developer Platform](#case-study-3-platform-team-internal-developer-platform) +4. [Case Study 4: Growth Team -- E-Commerce Marketplace](#case-study-4-growth-team-e-commerce-marketplace) +5. [Patterns Across Case Studies](#patterns-across-case-studies) + +--- + +## Case Study 1: B2B SaaS -- Project Management Tool + +### Context + +**Company:** Mid-stage B2B SaaS company (200 employees) building a project management tool for marketing teams. 15,000 paying customers, $20M ARR. + +**Team:** Product trio -- Priya (PM), Jake (designer), and Lena (engineer). They've been a team for 4 months. + +**Assigned outcome:** Increase 90-day retention for new accounts from 62% to 75%. + +### Establishing the Practice + +**Week 1-2: Setting up the cadence** + +Priya's first step was automating interview recruitment. The team added an in-app banner for users in their first 30 days: "Help us make [Product] better for your team. Chat for 25 minutes and get a $25 gift card." This fed into a Calendly link with two weekly slots -- Tuesday at 2pm and Thursday at 10am. + +The team created a shared Miro board for their Opportunity Solution Tree, with the outcome ("Increase 90-day retention from 62% to 75%") at the top and empty space below for opportunities. + +**Week 3-4: First interviews and experience mapping** + +In the first two weeks, the trio conducted 4 interviews with users who were 2-3 weeks into their accounts. They asked each user: "Tell me about the last time you tried to set up a project in [Product]. Start from the very beginning." + +The stories revealed a consistent pattern: users understood how to create projects, but they struggled to get their team members to adopt the tool. One user said: "I spent an hour setting it up perfectly, then sent the link to my team, and nobody logged in. I felt like an idiot." + +The team built an experience map of "Getting your team onto a new project tool" and identified five distinct steps, with the biggest pain point at "getting team members to log in and start using it." + +### The Opportunity Solution Tree Takes Shape + +After 6 interviews, the team's OST looked like this: + +``` +Outcome: Increase 90-day retention from 62% to 75% +│ +├── "Account creator can't get team members to adopt the tool" +│ ├── "Team members don't understand why they should switch" +│ ├── "First login experience is confusing for invited members" +│ └── "No accountability -- nobody knows if team is using it" +│ +├── "Users can't figure out which features are relevant to their workflow" +│ └── "Marketing teams have different workflows than the default templates" +│ +└── "Users lose momentum after initial setup" + ├── "No reason to come back daily" + └── "Progress isn't visible to the person who advocated for the tool" +``` + +### Assumption Testing + +The team decided to focus on "Account creator can't get team members to adopt the tool" because 5 of 6 interviews mentioned this struggle. They brainstormed three solutions: + +1. **Onboarding buddy system:** Pair the account creator with a CS rep for the first 2 weeks +2. **Team adoption dashboard:** Show the creator which team members have logged in, completed tasks, etc. +3. **Magic invite link:** Pre-populate the invited member's view with their first assigned task so they immediately see why they need to log in + +For the "magic invite link" solution, the riskiest assumption was: "Team members will engage if they see an assigned task rather than an empty dashboard." They designed a painted-door test: existing invite emails were A/B tested. Version A was the current generic invite. Version B said "You have a task waiting for you in [Product]" (the task was the standard onboarding tutorial, reframed). + +**Result:** Version B had 34% higher click-through and 22% higher day-1 activation. The assumption was validated. + +### Outcome + +Over 8 weeks, the team shipped an improved invite flow based on validated assumptions. After one quarter of continuous discovery, 90-day retention moved from 62% to 71%. Not yet at the 75% target, but the team had clear evidence pointing to the next opportunities to pursue. + +--- + +## Case Study 2: Consumer Mobile -- Fitness App + +### Context + +**Company:** Early-stage startup (20 employees) with a mobile fitness app targeting busy professionals who want to exercise but struggle to maintain a routine. 50,000 MAU, freemium model. + +**Team:** Product trio -- Marcus (PM), Ava (designer), and Chen (engineer). This is their first time practicing continuous discovery. + +**Assigned outcome:** Increase 7-day retention (users active on day 1 and day 7) from 25% to 40%. + +### Getting Started with Limited Resources + +Marcus had no budget for a research platform, so they started scrappy. Ava added a single screen after the user's third workout: "We're building this app for people like you. Got 20 minutes for a quick call? We'll give you a free month of premium." This generated 3-4 willing participants per week. + +The trio blocked Thursday at 3pm as their standing interview slot. They created a simple Google Doc template for their interview snapshots. + +### Key Discovery: The Motivation Gap + +The first 5 interviews revealed something the team hadn't expected. Users weren't leaving because the workouts were bad -- they left because they couldn't figure out which workout to do on any given day. + +One user described it: "I open the app on Monday feeling motivated. I see 200 workouts. I spend 5 minutes scrolling, can't decide, and close the app. By Wednesday my motivation is gone." + +Another user: "The app has great content, but it feels like a library, not a coach. I don't need more options -- I need someone to tell me 'do this today.'" + +The team mapped the experience of "deciding what workout to do today" and found that the decision point was where most users dropped off. The experience map showed: + +1. Open app with intention to work out +2. Browse workout library (feeling: overwhelmed) +3. Try to filter or search (feeling: frustrated -- too many options) +4. Either pick something random or give up (feeling: defeated or unsatisfied) +5. If they picked something, do the workout (feeling: good during, but uncertain if it was the "right" choice) + +### Opportunity Solution Tree + +``` +Outcome: Increase 7-day retention from 25% to 40% +│ +├── "I can't decide which workout to do today" ← FOCUS +│ ├── "I don't know what's appropriate for my fitness level" +│ ├── "I don't have a plan -- every day feels like starting over" +│ └── "There are too many options and I'm overwhelmed" +│ +├── "I lose motivation when I don't see progress" +│ └── "I can't tell if I'm getting stronger or fitter" +│ +└── "Life gets in the way and I fall off the routine" + └── "Once I miss a day, I feel guilty and avoid the app" +``` + +### Testing Assumptions + +The team focused on "I don't have a plan -- every day feels like starting over" because it appeared in 4 of 5 interviews and was connected to the strongest emotional language. + +**Solution idea:** A simple daily plan that tells users exactly which workout to do today based on their stated goals, available time, and equipment. + +**Riskiest assumption:** "Users will follow a prescribed daily plan instead of browsing on their own." + +**Test:** They created a Wizard of Oz test. For 20 users who opted in, Ava manually selected a daily workout based on their profile and sent a push notification each morning: "Today's workout: [name] (25 min, upper body). Tap to start." Marcus tracked how many tapped the notification and completed the workout. + +**Result:** 14 of 20 users (70%) completed the recommended workout on day 1. By day 7, 11 of 20 (55%) were still following the daily plan. Compared to the 25% baseline retention, this was a dramatic improvement. + +### Outcome + +The team built a lightweight recommendation engine based on what they learned from the Wizard of Oz test. Day-7 retention climbed to 38% within 6 weeks. The continuous interview cadence continued to reveal refinements -- users wanted to swap workouts without losing their plan, and they wanted a "rest day" option that didn't feel like failure. + +--- + +## Case Study 3: Platform Team -- Internal Developer Platform + +### Context + +**Company:** Large enterprise (5,000 employees) with an internal platform team that builds tools for the company's 300 software engineers. + +**Team:** Product trio -- Sam (PM), Robin (designer), and Alex (engineer). Their "customers" are internal developers. + +**Assigned outcome:** Reduce average deployment time from 45 minutes to under 15 minutes. + +### Adapting Discovery for Internal Customers + +Sam's advantage was direct access to customers -- they sat in the same Slack channels. The challenge was that internal developers had strong opinions about solutions ("just give us better CI/CD pipelines") but rarely articulated the underlying needs. + +The team set up a weekly "Deploy Stories" interview. Every Thursday, they invited one developer to walk through their most recent deployment step by step. The framing was crucial: "We're not asking what tools you want -- we want to understand your actual experience of deploying code last week." + +### Surprising Findings + +The team assumed the slow deployment was a CI/CD pipeline problem. The experience map told a different story: + +1. **Write code and get it reviewed** (15 min, well-understood) +2. **Merge to main** (2 min, no pain) +3. **Wait for CI to run** (8 min -- the part the team expected to be the bottleneck) +4. **Manually check 3 dashboards to verify the deploy is healthy** (12 min -- unexpected) +5. **Write a deploy summary in Slack for the on-call engineer** (5 min -- unknown to the platform team) +6. **Wait for the on-call engineer to acknowledge** (variable: 3-20 min -- the actual bottleneck) + +Steps 4, 5, and 6 accounted for more time than CI (step 3) and were entirely manual. The platform team had been investing in CI speed while the real time sinks were elsewhere. + +### The OST Reframed + +``` +Outcome: Reduce deployment time from 45 min to under 15 min +│ +├── "I have to manually check multiple dashboards to verify deploy health" +│ ├── "I don't trust that the deploy is healthy without checking myself" +│ └── "Each dashboard shows different metrics and I'm not sure what to look for" +│ +├── "I have to write a manual deploy summary and wait for acknowledgment" +│ ├── "The summary format isn't standardized so I spend time figuring out what to include" +│ └── "The on-call person doesn't always see my message quickly" +│ +└── "CI takes 8 minutes and I context-switch during the wait" + └── "By the time CI finishes, I've started something else and don't come back for 10+ min" +``` + +### Evidence-Driven Solutions + +Instead of optimizing CI (which would have saved 2-3 minutes at best), the team focused on the deploy verification and handoff steps. They tested a simple assumption: "Developers will trust an automated health check if it shows the same metrics they currently check manually." + +They built a prototype that aggregated the three dashboards into a single deploy health summary posted automatically in Slack. Seven developers tested it for one week. Six of seven said they no longer needed to check the dashboards separately. The seventh wanted one additional metric included. + +### Outcome + +By automating health verification and deploy summaries, the team reduced average deployment time from 45 minutes to 18 minutes -- without touching the CI pipeline at all. Continuous interviews continued to reveal further optimizations, and the team estimated they could reach the 15-minute target within another quarter. + +--- + +## Case Study 4: Growth Team -- E-Commerce Marketplace + +### Context + +**Company:** Series B e-commerce marketplace connecting independent artisans with buyers. 200,000 registered buyers, 8,000 sellers. + +**Team:** Product trio -- Dana (PM), Leo (designer), and Nia (engineer). They sit on the growth team focused on buyer-side metrics. + +**Assigned outcome:** Increase first-purchase conversion from 12% to 20% (percentage of registered users who make a purchase within 30 days). + +### Two-Sided Discovery + +The team's challenge was that their outcome depended on both sides of the marketplace. They needed to understand why buyers registered but didn't purchase. They split their interview cadence: + +- **Tuesdays:** Interview a registered buyer who hadn't purchased yet (recruited via email: "We noticed you signed up but haven't found anything yet -- can we learn why?") +- **Thursdays:** Interview a buyer who did make their first purchase within 30 days (recruited via post-purchase email) + +This contrast was powerful. By interviewing both converters and non-converters, the team could identify what was different about their experiences. + +### The Discovery + +Non-converter interviews revealed three dominant patterns: + +**Pattern 1 (mentioned in 7 of 10 non-converter interviews):** "I browsed for a while but couldn't tell if the products were actually good quality. The photos looked nice but I wasn't sure about sizing, materials, or durability." + +**Pattern 2 (mentioned in 5 of 10):** "I found something I liked but the shipping cost surprised me at checkout. I thought 'I'll come back later' and never did." + +**Pattern 3 (mentioned in 4 of 10):** "I signed up because someone shared a link to a specific product, but when I looked at the rest of the site, nothing else caught my eye." + +Converter interviews showed a contrasting pattern: buyers who purchased often mentioned reading reviews, seeing detailed product descriptions, or having a friend recommend a specific seller. + +### Opportunity Solution Tree + +``` +Outcome: Increase first-purchase conversion from 12% to 20% +│ +├── "I can't assess product quality from the listing" ← PRIMARY FOCUS +│ ├── "Photos don't show scale, materials, or details" +│ ├── "I don't trust reviews -- are they real?" +│ └── "I can't find information about the seller's craftsmanship" +│ +├── "Shipping costs surprise me and kill my motivation to buy" +│ ├── "I don't see shipping costs until checkout" +│ └── "Shipping feels too expensive relative to the product" +│ +└── "After seeing the product I came for, I don't discover anything else" + └── "The 'recommended for you' section isn't relevant to my interests" +``` + +### Assumption Testing + +For the primary focus opportunity, the team generated three solutions: + +1. **Enhanced listing requirements:** Require sellers to include size reference photos and material close-ups +2. **Verified review badges:** Show which reviews come from verified purchases +3. **Seller story cards:** Short profiles showing the artisan's workshop and process + +The riskiest assumption for seller story cards was: "Seeing the artisan's story will increase buyer confidence in product quality." They tested this with a simple experiment: for 500 product views, they added a one-line artisan bio with a workshop photo at the top of the listing. For another 500 views (control), the listing was unchanged. + +**Result:** Listings with artisan context had 18% higher add-to-cart rates and 11% higher checkout completion. Buyers spent an average of 8 seconds longer on the listing -- suggesting they were reading the context and it influenced their decision. + +For the shipping cost opportunity, they tested upfront shipping display. The assumption: "Showing shipping costs on the product listing page (instead of at checkout) will reduce cart abandonment without significantly reducing add-to-cart rates." They ran an A/B test on 2,000 product views. + +**Result:** Showing shipping costs upfront reduced add-to-cart by 5% but increased checkout completion by 23%. Net effect: more completed purchases. The transparency removed the unpleasant surprise. + +### Outcome + +Over 10 weeks, the team shipped artisan context cards, verified review badges, and upfront shipping display. First-purchase conversion moved from 12% to 17.5%. The continuous interview cadence revealed that the next biggest opportunity was in the post-first-purchase experience -- buyers who had a good first experience but didn't come back for a second purchase. + +--- + +## Patterns Across Case Studies + +### 1. The Real Problem Is Rarely Where You Expect It + +- The B2B team thought retention was a feature problem; it was a team adoption problem +- The fitness team thought content quality was the issue; it was decision fatigue +- The platform team thought CI speed was the bottleneck; it was manual verification +- The growth team thought conversion was about product appeal; it was about trust signals + +**Lesson:** Continuous discovery's greatest value is correcting the team's initial assumptions about where the problem lies. + +### 2. Interviews Reveal What Data Cannot + +Analytics showed the platform team that deployments took 45 minutes. Only interviews revealed that 25 of those minutes were spent on manual steps invisible to the deployment pipeline. + +**Lesson:** Quantitative data tells you what is happening. Qualitative interviews tell you why. + +### 3. Small Tests Prevent Big Mistakes + +Every team ran cheap tests before committing to building. The fitness team's Wizard of Oz test cost zero engineering effort. The marketplace team's artisan story card test was a simple content addition. + +**Lesson:** The cheapest test that generates evidence is always the right first step. + +### 4. The Cadence Compounds + +In each case study, the team's understanding deepened over weeks. Early interviews revealed surface-level problems. Later interviews, informed by earlier learning, probed deeper and uncovered root causes. + +**Lesson:** Individual interviews are informative. A sustained cadence of interviews is transformative. + +### 5. The Trio Makes Better Decisions Together + +When PM, designer, and engineer all hear the same customer stories, alignment happens naturally. There's no need for lengthy requirements documents or persuasion -- everyone saw the user struggle with the same pain point. + +**Lesson:** Shared evidence creates shared conviction. The product trio interviewing together is not a luxury; it's a prerequisite for good decisions. diff --git a/.agents/skills/continuous-discovery/references/experience-mapping.md b/.agents/skills/continuous-discovery/references/experience-mapping.md new file mode 100644 index 00000000..adc51cfa --- /dev/null +++ b/.agents/skills/continuous-discovery/references/experience-mapping.md @@ -0,0 +1,253 @@ +# Experience Mapping + +A guide to creating current-state experience maps that reveal customer pain points, emotions, and unmet needs -- turning interview data into actionable opportunities for the Opportunity Solution Tree. + +## What Is an Experience Map? + +An experience map is a visual representation of how a customer accomplishes a specific goal today, capturing each step they take, what they think and feel at each step, and where they struggle. Unlike a journey map (which tracks interactions with your product), an experience map captures the customer's full experience regardless of which tools, products, or workarounds they use. + +### Experience Map vs. Journey Map + +| Aspect | Experience Map | Journey Map | +|--------|---------------|-------------| +| **Scope** | The customer's entire experience of accomplishing a goal | Interactions with your specific product | +| **Perspective** | Customer-centered | Product-centered | +| **When to use** | Understanding the problem space; finding opportunities | Optimizing an existing product experience | +| **Includes** | Competitor usage, manual workarounds, offline steps | Your product's touchpoints only | +| **Discovery value** | High -- reveals unmet needs and new opportunities | Medium -- reveals friction in existing flows | + +**Rule of thumb:** In continuous discovery, start with experience maps. They reveal the full landscape of opportunities. Use journey maps later to optimize specific product flows. + +## Anatomy of an Experience Map + +### The Five Rows + +A well-structured experience map has five horizontal rows that run across each step of the experience: + +``` +┌──────────┬──────────┬──────────┬──────────┬──────────┐ +│ Step 1 │ Step 2 │ Step 3 │ Step 4 │ Step 5 │ +├──────────┼──────────┼──────────┼──────────┼──────────┤ +│ DOING │ DOING │ DOING │ DOING │ DOING │ +│ (actions)│ (actions)│ (actions)│ (actions)│ (actions)│ +├──────────┼──────────┼──────────┼──────────┼──────────┤ +│ THINKING │ THINKING │ THINKING │ THINKING │ THINKING │ +│(questions│(questions│(questions│(questions│(questions│ +│ & goals) │ & goals) │ & goals) │ & goals) │ & goals) │ +├──────────┼──────────┼──────────┼──────────┼──────────┤ +│ FEELING │ FEELING │ FEELING │ FEELING │ FEELING │ +│(emotions)│(emotions)│(emotions)│(emotions)│(emotions)│ +├──────────┼──────────┼──────────┼──────────┼──────────┤ +│ PAIN │ PAIN │ PAIN │ PAIN │ PAIN │ +│ POINTS │ POINTS │ POINTS │ POINTS │ POINTS │ +├──────────┼──────────┼──────────┼──────────┼──────────┤ +│ OPPS │ OPPS │ OPPS │ OPPS │ OPPS │ +│(needs) │(needs) │(needs) │(needs) │(needs) │ +└──────────┴──────────┴──────────┴──────────┴──────────┘ +``` + +**Row 1 -- Doing (Actions):** What the customer physically does at this step. Be specific: "Opens three browser tabs to compare prices" not "Researches options." + +**Row 2 -- Thinking (Questions & Goals):** What the customer is trying to figure out or decide. "Am I getting a good deal?" "Is this the right size?" "What do other people recommend?" + +**Row 3 -- Feeling (Emotions):** The emotional state at this step. Use specific emotion words: frustrated, anxious, confident, overwhelmed, relieved, excited, bored. + +**Row 4 -- Pain Points:** Where the experience breaks down. Long waits, confusing interfaces, missing information, forced workarounds, dead ends. + +**Row 5 -- Opportunities:** Customer needs that emerge from the pain points and emotions. These feed directly into the OST. + +## How to Build an Experience Map + +### Step 1: Choose the Experience to Map + +Select a specific goal that your target customers are trying to accomplish. The scope should be: +- **Broad enough** to capture the full experience (not just the part involving your product) +- **Narrow enough** to be mappable in a single session (not "manage their entire business") + +| Too Broad | Too Narrow | Just Right | +|-----------|-----------|------------| +| "Manage finances" | "Click the save button" | "Prepare and file quarterly taxes" | +| "Do marketing" | "Write an email subject line" | "Plan and execute a product launch campaign" | +| "Stay healthy" | "Log a meal" | "Decide what to eat for a healthy weeknight dinner" | + +### Step 2: Gather the Data + +Experience maps must be built from real customer data, not team assumptions. Sources include: + +| Source | What It Provides | How to Use | +|--------|-----------------|------------| +| Interview snapshots | Specific stories about how customers accomplish the goal | Extract steps, emotions, and pain points from stories | +| Support tickets | Common failure points and confusion | Map where in the experience breakdowns occur | +| Analytics / session recordings | What users actually do in your product | Validate or challenge interview findings | +| Contextual inquiry | Direct observation of users in their environment | Capture steps that users don't think to mention | + +**Minimum data:** At least 5 interview snapshots describing the same general experience before attempting to map it. Fewer than 5 and the map will reflect individual stories, not patterns. + +### Step 3: Map the Steps + +Lay out the major steps of the experience from beginning to end. Start rough and refine. + +**Process:** +1. Review interview snapshots and list every distinct step mentioned +2. Arrange steps in chronological order +3. Merge similar steps described by different participants +4. Add steps that participants implied but didn't explicitly state +5. Validate the sequence: does this flow make sense? + +**Example -- "Hiring a contractor for home renovation":** +1. Realize renovation is needed +2. Research what's involved and set a budget +3. Ask friends and search online for contractors +4. Contact 3-5 contractors for estimates +5. Compare estimates and check references +6. Select a contractor and negotiate terms +7. Manage the project during renovation +8. Inspect and approve the finished work +9. Handle issues or follow-up repairs + +### Step 4: Fill In the Rows + +For each step, use interview data to populate the Doing, Thinking, Feeling, and Pain Point rows. + +**Example -- Step 4: "Contact 3-5 contractors for estimates":** +- **Doing:** Calling phone numbers, leaving voicemails, sending emails, filling out contact forms on websites +- **Thinking:** "How many should I contact?" "What should I ask?" "How do I compare their responses?" +- **Feeling:** Anxious about making the right choice, frustrated when calls go to voicemail, overwhelmed by different formats of estimates +- **Pain Points:** Many contractors don't call back; estimates come in different formats making comparison difficult; no standard way to evaluate quality + +### Step 5: Identify Opportunities + +Review each pain point and emotion peak on the map and translate them into opportunity statements for the OST. + +**Translation examples:** + +| Pain Point | Opportunity Statement | +|------------|----------------------| +| Estimates come in different formats | "Homeowners need a way to compare contractor estimates on an apples-to-apples basis" | +| Many contractors don't call back | "Homeowners need a reliable way to reach responsive contractors" | +| Overwhelmed by different options | "Homeowners need guidance on what criteria matter most for their specific project" | + +## Collaborative Mapping Exercises + +### The Workshop Format (2-3 Hours) + +Experience maps are most valuable when built collaboratively by the product trio. The exercise creates shared understanding that no document can replicate. + +**Participants:** Product manager, designer, engineer(s), and optionally: data analyst, customer success representative + +**Materials:** Large wall or digital whiteboard, sticky notes (physical or virtual), markers, printed interview snapshots + +**Agenda:** + +| Time | Activity | Purpose | +|------|----------|---------| +| 0-15 min | Review the goal and scope of the experience to map | Align on boundaries | +| 15-45 min | Individual review: each person reads 3-5 snapshots and writes steps on stickies | Gather diverse perspectives | +| 45-75 min | Collaborative arrangement: place steps on the wall, discuss sequence, merge duplicates | Build shared timeline | +| 75-105 min | Fill in rows: add Doing, Thinking, Feeling, Pain Points for each step | Deepen understanding | +| 105-135 min | Identify opportunities: translate pain points into opportunity statements | Connect to the OST | +| 135-150 min | Prioritize: which opportunities are most impactful and best supported by evidence? | Focus the team | + +### Facilitation Tips + +- **Start with divergence:** Let each person work independently before coming together, to avoid groupthink +- **Use quotes:** Place verbatim customer quotes on the map to keep it grounded +- **Mark confidence levels:** Use dots or colors to indicate which steps are well-supported by evidence (green) vs. assumed (red) +- **Capture disagreements:** When team members see the experience differently, that's valuable -- it reveals where you need more data +- **Time-box ruthlessly:** It's better to have a rough complete map than a detailed partial one + +### Remote Collaboration + +For distributed teams, use digital whiteboarding tools (Miro, FigJam, Mural) with these adaptations: +- Pre-populate the template before the session +- Use breakout rooms for the individual review phase +- Assign a facilitator to manage the digital board and prevent chaos +- Record the session for team members who can't attend + +## Using Maps to Generate Opportunities + +### The Opportunity Extraction Process + +After the map is built, systematically scan it for opportunities: + +**1. Emotion peaks:** Where do feelings become strongly negative (frustrated, anxious, overwhelmed) or surprisingly positive (relieved, delighted)? Negative peaks are unmet needs; positive peaks are moments to protect or amplify. + +**2. Workarounds:** Where are customers cobbling together multiple tools, doing manual work, or inventing their own solutions? Workarounds signal high-value unmet needs -- the customer is already motivated enough to create their own solution. + +**3. Drop-off points:** Where do customers abandon the experience or give up? These are the highest-friction moments and represent either simplification opportunities or entirely new approaches. + +**4. Handoff points:** Where does the customer move from one tool, person, or context to another? Handoffs create information loss, confusion, and frustration. + +**5. Wait times:** Where does the customer have to wait -- for information, for another person, for a process to complete? Waiting creates anxiety and abandonment. + +### Opportunity Quality Check + +For each opportunity extracted from the map, verify: + +| Check | Question | If No | +|-------|----------|-------| +| Customer-framed | Is this stated from the customer's perspective? | Rewrite: "Users need..." not "We should build..." | +| Evidence-based | Is this supported by at least 2-3 interview stories? | Flag as hypothesis; gather more evidence | +| Solution-agnostic | Does this describe a need without prescribing a solution? | Remove the implied solution; focus on the need | +| Actionable scope | Is this specific enough to generate solution ideas? | Break into sub-opportunities | + +## Maintaining Maps Over Time + +Experience maps are living documents that should evolve as the team conducts more interviews and the product changes. + +### Update Triggers + +| Trigger | What to Update | +|---------|---------------| +| New interview reveals a step you missed | Add the step and associated rows | +| Multiple interviews contradict a step on the map | Revise the step or split into segments | +| Your product changes the experience | Update affected steps; look for new pain points | +| A competitor enters the space | Map how the experience changes with the competitor's solution | +| You expand to a new customer segment | Create a parallel map for the new segment; compare | + +### When to Create a New Map vs. Update an Existing One + +- **Update** when the goal is the same but details have changed +- **Create new** when you're exploring a different goal or a significantly different customer segment +- **Archive** old maps rather than deleting them -- they provide historical context + +## Example: Complete Experience Map + +### Experience: "Small business owner creating and sending an invoice" + +**Step 1 -- Complete the work** +- Doing: Finishing the project, tracking hours, gathering receipts +- Thinking: "Did I track everything? Am I forgetting any billable items?" +- Feeling: Relieved work is done, anxious about accuracy +- Pain: No single place where all billable items live; have to check email, time tracker, and notes + +**Step 2 -- Create the invoice** +- Doing: Opening invoicing tool, entering line items, adding client details +- Thinking: "What's the right format? Do I need a PO number? What's the tax rate?" +- Feeling: Tedious, worried about looking professional +- Pain: Re-entering information that exists elsewhere; unsure about tax rules + +**Step 3 -- Review and send** +- Doing: Proofreading, saving as PDF, attaching to email, writing a message +- Thinking: "Does this look professional? Will they pay on time?" +- Feeling: Anxious about the payment timeline, insecure about professionalism +- Pain: Manual process of export-attach-email; no tracking of whether client received it + +**Step 4 -- Wait for payment** +- Doing: Checking bank account, checking email for confirmation +- Thinking: "Did they get it? Should I follow up? When is it rude to ask?" +- Feeling: Anxious, uncertain, sometimes resentful +- Pain: No visibility into whether invoice was viewed; unclear payment timeline + +**Step 5 -- Follow up on late payment** +- Doing: Writing a follow-up email, calling the client, feeling awkward +- Thinking: "How do I ask without damaging the relationship?" +- Feeling: Frustrated, uncomfortable, dreading the conversation +- Pain: No standard follow-up process; feels personal rather than professional + +**Opportunities extracted:** +1. "Business owners need all billable items in one place so nothing falls through the cracks" +2. "Business owners need to create professional invoices without re-entering data they've already recorded" +3. "Business owners need visibility into whether a client has seen an invoice" +4. "Business owners need a way to follow up on late payments that feels professional, not personal" +5. "Business owners need clarity on tax rules relevant to their specific invoices" diff --git a/.agents/skills/continuous-discovery/references/interview-snapshots.md b/.agents/skills/continuous-discovery/references/interview-snapshots.md new file mode 100644 index 00000000..5ff3b27c --- /dev/null +++ b/.agents/skills/continuous-discovery/references/interview-snapshots.md @@ -0,0 +1,254 @@ +# Interview Snapshots + +A practical guide to conducting story-based customer interviews, capturing insights in a standardized snapshot format, and building a sustainable weekly interview cadence. + +## Story-Based Interviewing + +### Why Stories, Not Opinions + +Traditional customer interviews ask people what they want, how they'd rate features, or whether they'd use a hypothetical product. These approaches fail because: + +| Approach | Why It Fails | What You Get | +|----------|-------------|--------------| +| "What features do you want?" | Customers design solutions, not needs | Feature requests disconnected from real problems | +| "Would you use X?" | Hypothetical questions get hypothetical answers | False positives -- people say yes to be polite | +| "How important is Y on a scale of 1-5?" | Everything is rated "important" with no context | Flat data with no insight into actual behavior | +| "What do you think of Z?" | Opinions don't predict behavior | Rationalizations, not revelations | + +Story-based interviewing asks customers to describe specific past experiences in rich detail. Real stories reveal what people actually did, felt, and struggled with -- not what they think they might do. + +### The Core Technique + +**The anchor question:** "Tell me about the last time you [did the relevant activity]." + +This single prompt unlocks a narrative. From there, follow up with: + +- **Sequence questions:** "What happened next?" "And then what did you do?" +- **Clarification questions:** "What do you mean by 'frustrating'?" "Can you walk me through that step by step?" +- **Emotion questions:** "How did that make you feel?" "What were you thinking at that point?" +- **Context questions:** "Where were you when this happened?" "Who else was involved?" +- **Contrast questions:** "Was that different from the time before?" "Have you ever done it differently?" + +### Interview Structure (30 Minutes) + +**Minutes 1-3: Warm-up** +- Thank the participant +- Explain the purpose: "We're trying to understand how you [activity] so we can make the experience better" +- Reassure: "There are no right or wrong answers -- we just want to learn from your real experience" +- Ask permission to record + +**Minutes 3-8: Context setting** +- "How often do you [activity]?" +- "How long have you been doing it this way?" +- "Who else is involved when you [activity]?" + +**Minutes 8-25: Story elicitation** +- "Tell me about the last time you [activity]. Start from the very beginning." +- Follow the story wherever it goes, using follow-up questions +- Probe pain points: "You mentioned that was annoying -- can you tell me more about that?" +- Probe workarounds: "You said you used a spreadsheet for that part -- walk me through why" +- Get specifics: "You said 'a while' -- was that minutes? Hours? Days?" + +**Minutes 25-30: Wrap-up** +- "Is there anything else about this experience that we haven't covered?" +- "What's the single most frustrating part of [activity]?" +- Thank the participant and explain next steps + +### Common Interview Mistakes + +| Mistake | Example | Fix | +|---------|---------|-----| +| Leading questions | "Don't you think it would be better if...?" | "How do you handle that situation today?" | +| Accepting vague answers | Customer says "it's fine" and you move on | "Can you tell me about a specific time it was fine? What happened?" | +| Pitching your solution | "We're building a feature that does X -- would you use it?" | Save solution ideas for after the interview | +| Talking more than listening | Interviewer fills silences with explanations | Embrace silence; count to 5 before speaking | +| Only interviewing happy customers | Recruiting from active power users | Include churned users, new users, and struggling users | +| Going hypothetical | "What would you do if...?" | "Tell me about a time when you actually faced that situation" | + +## The Interview Snapshot Format + +After each interview, the product trio fills out a one-page snapshot. The goal is a concise, scannable artifact that anyone on the team can read in two minutes. + +### Snapshot Template + +``` +┌─────────────────────────────────────────────────────┐ +│ INTERVIEW SNAPSHOT │ +│ │ +│ Date: [date] Participant: [name/alias] │ +│ Interviewer(s): [names] │ +│ Role/Segment: [description] │ +│ │ +│ ── THE STORY ──────────────────────────────────────│ +│ [2-3 sentence summary of the specific experience │ +│ the participant described] │ +│ │ +│ ── KEY QUOTES ─────────────────────────────────────│ +│ • "[verbatim quote 1]" │ +│ • "[verbatim quote 2]" │ +│ • "[verbatim quote 3]" │ +│ │ +│ ── OPPORTUNITIES IDENTIFIED ───────────────────────│ +│ • [Opportunity 1 -- framed as customer need] │ +│ • [Opportunity 2 -- framed as customer need] │ +│ │ +│ ── SURPRISES / NEW INSIGHTS ───────────────────────│ +│ • [Something unexpected that challenges our │ +│ assumptions] │ +│ │ +│ ── FOLLOW-UP ──────────────────────────────────────│ +│ • [Questions to explore in future interviews] │ +│ • [Data to look up] │ +│ │ +└─────────────────────────────────────────────────────┘ +``` + +### Filling Out the Snapshot + +**Timing:** Complete the snapshot immediately after the interview, while the conversation is fresh. This should take 10-15 minutes for the trio together. + +**The Story section:** Write 2-3 sentences that capture the specific experience the participant described. Not a summary of everything they said -- the core narrative arc. Example: "Maria described her weekly process of preparing client reports. She spends 2 hours every Monday manually pulling data from three different tools into a spreadsheet, then another hour formatting it. She sends the report by email and rarely hears back, so she doesn't know if clients actually read it." + +**Key Quotes:** Write down 2-4 verbatim quotes that were particularly revealing. These are gold for communicating customer voice to stakeholders. Example: "I just copy and paste from three different dashboards. It's ridiculous, but I don't know a better way." + +**Opportunities Identified:** Translate pain points and unmet needs into opportunity statements. These should be framed from the customer's perspective and be solution-agnostic. Example: "Users need a way to aggregate data from multiple sources without manual copy-paste." + +**Surprises:** Capture anything that challenged the team's assumptions or was genuinely new. This section forces the team to acknowledge what they didn't know. + +## Synthesizing Across Interviews + +Individual interviews tell stories. Patterns across interviews reveal opportunities. Synthesis is how you move from anecdotes to evidence. + +### The Synthesis Process + +**Weekly (after each interview):** +1. Complete the interview snapshot +2. Add new opportunities to the Opportunity Solution Tree +3. Note if the opportunity reinforces a pattern seen in prior interviews + +**Bi-weekly (every 2 weeks):** +1. Lay out all recent snapshots side by side +2. Look for recurring themes across participants +3. Cluster similar opportunities together +4. Identify which opportunities have the most supporting evidence +5. Update the OST with refined opportunity framing + +**Monthly:** +1. Review the full snapshot library +2. Assess coverage: are we hearing from diverse segments? +3. Identify gaps: what questions remain unanswered? +4. Adjust recruitment strategy based on gaps + +### Identifying Patterns + +| Signal | What It Means | Action | +|--------|---------------|--------| +| 3+ participants describe the same pain point | Strong opportunity with broad impact | Promote to a primary opportunity on the OST | +| Different segments describe the same need differently | Opportunity may need sub-opportunities by segment | Break into segment-specific sub-opportunities | +| One participant describes something nobody else mentioned | Could be an outlier or an early signal | Keep it noted; look for it in the next 3-5 interviews | +| Participants describe workarounds for the same gap | Unmet need that customers are actively trying to solve | High-priority opportunity -- customers already want a solution | +| Emotional language appears around a specific moment | High-impact pain point with emotional resonance | Opportunity with strong desirability signal | + +### Avoiding Synthesis Pitfalls + +- **Recency bias:** The most recent interview feels most important. Counter by reviewing all recent snapshots together. +- **Confirmation bias:** You notice patterns that confirm what you already believe. Counter by specifically looking for disconfirming evidence. +- **Loudest voice:** One particularly articulate participant's story dominates thinking. Counter by counting -- how many participants mentioned this? +- **Premature closure:** You stop interviewing once you hear a pattern. Counter by continuing interviews even when you think you've found the answer. + +## Extracting Opportunities from Stories + +### The Translation Process + +Stories contain raw data. Opportunities are insights extracted from that data. The translation requires separating what customers did and felt from what the team might do about it. + +**Step 1: Identify the pain point or unmet need in the story** +- Customer action: "I export data to a spreadsheet, then reformat it manually" +- Pain point: Manual data transformation is time-consuming and error-prone + +**Step 2: Frame it from the customer's perspective** +- Bad: "We need to add a data export feature" (solution-framed) +- Good: "Users need their data in a usable format without manual transformation" (need-framed) + +**Step 3: Validate the scope** +- Is this too broad? ("Users need data") -- break it down +- Is this too narrow? ("Users need CSV export with custom columns") -- zoom out +- Just right: specific enough to be actionable, broad enough to allow multiple solutions + +## Automating Recruitment + +The biggest reason teams stop doing weekly interviews is that recruitment is painful. Automation makes the habit sustainable. + +### Recruitment Channels + +| Channel | Best For | Setup Effort | Ongoing Effort | +|---------|----------|-------------|----------------| +| In-app intercept | Active users; behavior-triggered targeting | Medium (requires engineering) | Very low | +| Email to existing users | Broad user base; can segment by behavior | Low | Low | +| Customer advisory panel | Power users willing to give regular feedback | Medium (need to curate panel) | Low | +| Support ticket follow-up | Users who experienced specific problems | Low | Medium (manual screening) | +| Scheduling tool (e.g., Calendly) | All channels; reduces back-and-forth | Very low | Very low | +| User research platform | Diverse participants including non-users | Low (subscription) | Low | + +### The Ideal Recruitment System + +1. **Trigger:** An in-app message appears to users who match your target criteria (e.g., users in their first week, users who haven't used feature X, users who recently churned) +2. **Opt-in:** The message says: "Help us make [product] better for you. Chat for 20-30 minutes and receive [incentive]." +3. **Scheduling:** Clicking the message opens a scheduling tool with the team's available slots +4. **Reminder:** Automatic email reminder 24 hours and 1 hour before the session +5. **Follow-up:** Automatic thank-you email with incentive delivery after the session + +### Incentive Guidelines + +| Audience | Appropriate Incentive | +|----------|----------------------| +| B2B enterprise users | Gift card ($50-100), donation to charity of choice | +| B2B SMB users | Gift card ($25-50), extended trial or credits | +| Consumer users (paid) | Gift card ($15-30), free month of service | +| Consumer users (free) | Gift card ($10-20), premium feature access | +| Churned users | Gift card ($30-50) -- harder to recruit, worth the premium | + +## The Weekly Interview Cadence + +### Minimum Viable Cadence + +- **One interview per week** with the full product trio present +- **10-15 minutes of snapshot synthesis** immediately after the interview +- **30 minutes of bi-weekly synthesis** reviewing patterns across recent snapshots + +### Scaling the Cadence + +As the team builds the habit, scale to 2-3 interviews per week: + +| Slot | Focus | Participant Type | +|------|-------|-----------------| +| Tuesday 2pm | Current problem space | Active users matching current opportunity | +| Thursday 10am | Broad discovery | Diverse user segments for new opportunities | +| Friday 11am (optional) | Specific investigation | Churned users, prospects, or edge cases | + +### What If You Can't Get Interviews? + +| Barrier | Workaround | +|---------|------------| +| "Our users won't talk to us" | Start with users who contact support -- they already want to talk | +| "We're B2B and can't reach end users" | Partner with customer success to join their regular calls | +| "Leadership says we don't have time" | Start with one 30-minute interview per week; the value will justify more | +| "We don't have users yet" | Interview people who match your target persona about their current experience | +| "Nobody shows up" | Increase incentive, send multiple reminders, over-recruit (book 5 to get 3) | + +## Snapshot Library Management + +### Organization + +Organize snapshots so the team can reference them easily: +- **Chronological:** Newest on top for scanning recent learning +- **Tagged by opportunity:** Each snapshot tagged with the opportunities it supports +- **Tagged by segment:** Each snapshot tagged with participant characteristics +- **Searchable:** Use a tool that allows keyword search across all snapshots + +### Using the Library + +- **Before designing a solution:** Pull up all snapshots related to the target opportunity +- **During stakeholder discussions:** Reference specific snapshots and quotes to ground conversations in evidence +- **When onboarding new team members:** Have them read the last 10-15 snapshots to build customer empathy quickly +- **During prioritization:** Count how many snapshots support each opportunity to assess evidence strength diff --git a/.agents/skills/continuous-discovery/references/opportunity-trees.md b/.agents/skills/continuous-discovery/references/opportunity-trees.md new file mode 100644 index 00000000..92910697 --- /dev/null +++ b/.agents/skills/continuous-discovery/references/opportunity-trees.md @@ -0,0 +1,214 @@ +# Opportunity Solution Trees + +A comprehensive guide to building, maintaining, and using Opportunity Solution Trees (OSTs) as the central artifact of continuous product discovery. + +## What Is an Opportunity Solution Tree? + +An Opportunity Solution Tree is a visual diagram that maps the path from a desired business outcome to the customer opportunities that could drive that outcome, the solutions that could address those opportunities, and the experiments that could test those solutions. + +### The Four Layers + +``` + [Desired Outcome] + | + ┌────────────┼────────────┐ + | | | +[Opportunity] [Opportunity] [Opportunity] + | | | | + [Sub-opp] [Solution] [Solution] [Sub-opp] + | | | | +[Solution] [Experiment] [Experiment] [Solution] + | | +[Experiment] [Experiment] +``` + +**Layer 1 -- Desired Outcome:** A measurable business or product metric the team is responsible for. Examples: increase trial-to-paid conversion from 8% to 15%, reduce time-to-value below 3 minutes, increase weekly active usage by 20%. + +**Layer 2 -- Opportunities:** Customer needs, pain points, and desires discovered through interviews and research. These are always framed from the customer's perspective. Example: "I can't tell if the product is worth paying for during the trial." + +**Layer 3 -- Solutions:** Specific product changes, features, or interventions that could address an opportunity. Multiple solutions can map to one opportunity. Example: "Add a guided tour that highlights premium features during trial." + +**Layer 4 -- Experiments:** Small, fast tests that validate whether a solution will work before the team commits to building it fully. Example: "Show a 30-second video walkthrough to 50% of trial users and measure upgrade rate." + +## How to Build an Opportunity Solution Tree + +### Step 1: Define the Outcome + +Work with leadership to identify a clear, measurable outcome for the team. Good outcomes are: +- **Measurable:** Has a number attached (conversion rate, retention, revenue) +- **Controllable:** The team can influence it through product changes +- **Time-bound:** Has a target date or review cadence +- **Customer-connected:** Improving this metric also improves the customer's life + +| Good Outcomes | Poor Outcomes | +|---------------|---------------| +| Increase 30-day retention from 40% to 55% | "Make the product better" | +| Reduce onboarding drop-off by 30% | "Ship feature X" (that's a solution, not an outcome) | +| Increase NPS from 32 to 50 | "Win more deals" (not directly controllable by product) | + +### Step 2: Populate the Opportunity Space + +Use interview data, support tickets, analytics, and experience maps to identify customer opportunities. For each opportunity, ask: +- Is this framed from the customer's perspective? +- Is this a need, pain point, or desire -- not a solution? +- Did this come from research, not just team brainstorming? + +**Common mistakes when writing opportunities:** +| What Teams Write | Why It's Wrong | Better Framing | +|-----------------|----------------|----------------| +| "Add search filters" | That's a solution | "Users can't find relevant items quickly" | +| "Users want a mobile app" | That's a solution disguised as a need | "Users need to check status on the go between meetings" | +| "Improve performance" | Too vague and internal-facing | "Pages take so long to load that users abandon tasks mid-flow" | + +### Step 3: Break Down Large Opportunities + +Large, abstract opportunities should be broken into smaller, more specific sub-opportunities. This makes them actionable and testable. + +**Example decomposition:** + +``` +"Users struggle with onboarding" + ├── "Users don't understand what the product does before signing up" + ├── "Users can't figure out how to complete their first task" + ├── "Users don't know which features are relevant to their role" + └── "Users lose motivation before experiencing the core value" +``` + +Each sub-opportunity can have its own solutions and experiments. The team can choose to focus on one sub-opportunity at a time. + +### Step 4: Generate Solutions + +For each prioritized opportunity, brainstorm multiple solutions. The goal is to have at least three distinct approaches so the team can compare rather than falling in love with the first idea. + +**Solution generation techniques:** +- **How Might We:** Reframe the opportunity as "How might we help users [opportunity]?" and brainstorm freely +- **Analogy mapping:** How do other industries or products solve a similar need? +- **Extreme constraints:** What would we do if we had only one day? One hour? No code changes? +- **Customer co-creation:** Show the opportunity to customers and ask how they'd solve it + +### Step 5: Design Experiments + +For each promising solution, identify the riskiest assumption and design a small test. See [assumption-mapping.md](assumption-mapping.md) for detailed assumption testing methodology. + +## Comparing Solutions on the Tree + +When multiple solutions map to the same opportunity, use these criteria to compare: + +| Criterion | Question | How to Evaluate | +|-----------|----------|-----------------| +| Reach | How many customers does this affect? | Analytics data on the affected segment | +| Impact | How much will this improve the opportunity? | Assumption test results, analogous evidence | +| Confidence | How much evidence do we have? | Number of supporting interviews, test results | +| Effort | How long will this take to build? | Engineering estimate (rough) | + +**Important:** Don't reduce this to a formula. Use the criteria to have an explicit conversation about tradeoffs. The goal is shared understanding, not a magic score. + +## Keeping the Tree Alive + +The OST is not a document you create once and file away. It is a living artifact that evolves weekly. + +### Weekly Update Rhythm + +| Activity | When | Who | +|----------|------|-----| +| Add new opportunities from interviews | After each interview | Product trio | +| Reorganize and re-cluster opportunities | Weekly synthesis session (30 min) | Product trio | +| Add or remove solutions based on new evidence | When assumption tests complete | Product trio | +| Review tree structure for completeness | Bi-weekly | Product trio + stakeholders | +| Update outcome metrics | Monthly | PM with data team | + +### Signs Your Tree Is Healthy + +- New opportunities are being added every week from fresh interviews +- The team can explain why they chose their current focus opportunity +- Solutions have been tested with assumption tests before being built +- Stakeholders can look at the tree and understand the team's strategy +- The tree has changed meaningfully in the last month + +### Signs Your Tree Is Dying + +- No new opportunities have been added in two or more weeks +- The tree was created once and lives in a forgotten document +- Solutions were added without connecting to a customer opportunity +- The team can't explain the relationship between their current work and the tree +- Opportunities are all written from the business perspective, not the customer's + +## Visual Tree Examples + +### Example 1: SaaS Trial Conversion + +``` +Outcome: Increase trial-to-paid conversion from 8% to 15% +│ +├── Opportunity: "I don't understand the value before trial ends" +│ ├── Sub: "I don't know which features to try first" +│ │ ├── Solution: Personalized onboarding checklist +│ │ └── Solution: Role-based guided tour +│ └── Sub: "I can't tell how this is better than my spreadsheet" +│ ├── Solution: Side-by-side comparison calculator +│ └── Solution: Import existing spreadsheet data +│ +├── Opportunity: "The pricing feels too high for what I've seen" +│ ├── Solution: Usage-based tier that starts cheaper +│ └── Solution: Highlight features user hasn't discovered +│ +└── Opportunity: "I forget about the trial and it expires" + ├── Solution: Smart reminder emails based on usage + └── Solution: Extend trial for active users automatically +``` + +### Example 2: Consumer App Retention + +``` +Outcome: Increase Day-30 retention from 20% to 35% +│ +├── Opportunity: "I run out of content that matches my interests" +│ ├── Solution: Improved recommendation algorithm +│ └── Solution: User-curated collections +│ +├── Opportunity: "I don't have a reason to come back daily" +│ ├── Sub: "There's nothing new since yesterday" +│ │ └── Solution: Daily digest of new relevant content +│ └── Sub: "I don't have a routine around using the app" +│ └── Solution: Morning briefing notification +│ +└── Opportunity: "I feel overwhelmed by too many choices" + ├── Solution: Simplified home screen with 3 picks + └── Solution: "Start here" single recommendation +``` + +## Common Anti-Patterns + +### The Solution Tree + +The tree has outcomes at the top and solutions at the bottom -- but no opportunity layer. This means the team is guessing at what customers need. + +**Fix:** Go back to interviews. Every solution on the tree must trace to a customer opportunity discovered through research. + +### The Wish List Tree + +The opportunity layer is populated with feature requests from customers or stakeholders: "users want dark mode," "users want an API." These are solutions masquerading as opportunities. + +**Fix:** Ask "why?" for each item. "Users want an API" becomes "Users need to connect our product to their existing workflow tools." + +### The Stale Tree + +The tree was created at the start of the quarter and hasn't been updated since. It no longer reflects what the team has learned. + +**Fix:** Schedule a 30-minute weekly session to update the tree with insights from that week's interviews. + +### The Disconnected Tree + +The tree exists but the team's actual sprint work doesn't connect to it. Features are being built that don't appear anywhere on the tree. + +**Fix:** Every sprint item should trace back to a solution on the tree. If it can't, either the tree is incomplete or the work isn't strategically aligned. + +## Tools and Formats + +The OST can be maintained in: +- **Physical whiteboard:** Best for co-located teams; highly visible and easy to modify +- **Digital whiteboarding tools:** Miro, FigJam, or Mural for remote teams +- **Dedicated tools:** ProductBoard, Vistaly, or Notion databases with relational views +- **Simple documents:** Even a nested bullet list in a shared doc works for small teams + +The format matters less than the discipline of updating it weekly. diff --git a/.agents/skills/continuous-discovery/references/prioritization-methods.md b/.agents/skills/continuous-discovery/references/prioritization-methods.md new file mode 100644 index 00000000..c1061ecc --- /dev/null +++ b/.agents/skills/continuous-discovery/references/prioritization-methods.md @@ -0,0 +1,267 @@ +# Prioritization Methods + +A guide to structured methods for comparing and ranking opportunities on the Opportunity Solution Tree, so product teams focus on the highest-leverage bets backed by evidence. + +## Why Structured Prioritization Matters + +Without a structured approach, teams default to prioritizing by: +- **HiPPO** (Highest Paid Person's Opinion) -- the loudest voice wins +- **Recency bias** -- whatever the last customer said becomes the top priority +- **Squeaky wheel** -- the most vocal internal stakeholder gets their feature built +- **Gut feeling** -- the PM "just knows" what's important + +Each of these leads to suboptimal outcomes because they skip the explicit tradeoff discussion that good prioritization requires. Structured methods don't eliminate judgment -- they channel it through a framework that surfaces disagreements early and ensures the team is aligned on why they're pursuing one opportunity over another. + +## Compare and Contrast Prioritization + +Teresa Torres recommends comparing opportunities head-to-head rather than scoring them independently. Independent scoring creates the illusion of objectivity while masking the real tradeoffs. Comparison forces the team to make explicit choices. + +### How It Works + +1. Take your top opportunities from the OST (ideally 5-7, no more than 10) +2. Compare each pair of opportunities across several dimensions +3. Through successive comparisons, a ranking emerges +4. The top-ranked opportunities become the team's focus + +### Comparison Dimensions + +| Dimension | Question to Ask | How to Evaluate | +|-----------|----------------|-----------------| +| **Opportunity size** | How many customers are affected? | Analytics data, segment sizes, interview frequency | +| **Frequency** | How often do customers encounter this need? | Interview stories, support ticket volume, usage data | +| **Severity** | How painful is this when it happens? | Emotional intensity in interviews, workaround complexity | +| **Strategic alignment** | Does this support our company's current strategy? | Team/company OKRs, leadership direction | +| **Evidence strength** | How much do we know about this opportunity? | Number of supporting interviews, data points | +| **Solution readiness** | Do we have promising solution ideas? | Quality and diversity of solutions mapped to this opportunity | + +### Running a Comparison Session + +**Time:** 60-90 minutes +**Participants:** Product trio (PM, designer, engineer) +**Preparation:** Each participant reviews the top opportunities and supporting evidence beforehand + +**Process:** + +1. **Round 1 -- Pair comparison (20 min):** + - Compare opportunity A vs. opportunity B on each dimension + - For each dimension, which opportunity is stronger? + - Record the "winner" of each pair + +2. **Round 2 -- Discussion (30 min):** + - Where did the trio disagree? Discuss those dimensions + - Surface the underlying assumptions behind disagreements + - Look for dimensions where the answer is genuinely unknown -- these signal a need for more evidence + +3. **Round 3 -- Stack rank (20 min):** + - Based on the pair comparisons and discussion, create a rough rank order + - The team doesn't need a perfect ranking -- they need to identify the top 2-3 opportunities to focus on + +4. **Decide (10 min):** + - Commit to a primary opportunity and a secondary opportunity + - Identify any "must-know" questions before committing further (these become interview questions for the next week) + +### Example Comparison + +**Opportunity A:** "Users can't find relevant content in search results" +- Size: Affects 70% of active users (based on analytics showing search usage) +- Frequency: Daily for most users +- Severity: Moderate -- users work around it but it takes extra time +- Evidence: 8 interview snapshots mention search frustration + +**Opportunity B:** "New users can't figure out how to complete their first project" +- Size: Affects 100% of new users (by definition) +- Frequency: Once per user, during onboarding +- Severity: High -- many users abandon before completing first project +- Evidence: 5 interview snapshots, plus analytics showing 60% drop-off at project creation + +**Discussion:** A affects more total interactions (daily * 70% of users), but B affects a critical moment (first-use experience). If users never complete their first project, they never become the daily users who'd benefit from search improvements. The team decides B is higher priority because it gates everything else. + +## Opportunity Scoring + +For teams that need a lightweight quantitative approach, opportunity scoring provides a structured framework. This works well when you need to communicate priorities to stakeholders who expect numeric justification. + +### Scoring Criteria + +| Criterion | Scale | How to Score | +|-----------|-------|-------------| +| **Reach** | 1-5 | How many customers will this affect in a given time period? | +| **Impact** | 1-5 | How much will this improve the target outcome? | +| **Confidence** | 1-5 | How much evidence do we have? (Interviews, data, test results) | +| **Effort** | 1-5 (inverted) | How much work is required? (5 = very little effort) | + +**Score = (Reach + Impact + Confidence + Effort) / 4** + +### Confidence Scoring Guide + +Confidence deserves special attention because it reflects the strength of your evidence: + +| Score | Evidence Level | Description | +|-------|---------------|-------------| +| 1 | Gut feeling | Team speculation with no customer data | +| 2 | Weak signal | 1-2 interview mentions; anecdotal | +| 3 | Moderate signal | 3-5 interview snapshots; some supporting data | +| 4 | Strong signal | 6+ interview snapshots; supporting analytics; tested assumptions | +| 5 | Validated | Assumption tests passed; prototype feedback positive; quantitative data confirms | + +### When Scoring Falls Short + +Scoring methods have real limitations: +- **False precision:** A score of 3.7 vs. 3.5 is meaningless noise, not a real difference +- **Dimension conflation:** Averaging across dimensions hides tradeoffs (a high-reach, low-impact opportunity looks the same as a low-reach, high-impact one) +- **Gaming:** Teams unconsciously inflate scores for opportunities they already prefer +- **Missing context:** Numbers don't capture the strategic narrative + +**Recommendation:** Use scoring as a starting point for discussion, not as a final decision. If the scores are close, switch to compare-and-contrast to resolve the tie. + +## Impact vs. Effort + +The classic 2x2 prioritization framework. Simple and intuitive, but should be used carefully. + +### The Matrix + +``` + HIGH IMPACT + │ + ┌────────────┼────────────┐ + │ │ │ + │ DO FIRST │ BIG BETS │ + │ (quick │ (worth the │ + │ wins) │ investment)│ + │ │ │ +LOW ─┼────────────┼────────────┼── HIGH +EFFORT│ │ │ EFFORT + │ FILL-INS │ AVOID │ + │ (do if │ (high cost,│ + │ capacity │ low return│ + │ allows) │ │ + └────────────┼────────────┘ + │ + LOW IMPACT +``` + +### Using It Well + +**Impact estimation:** Base impact on customer evidence, not team opinion. An opportunity mentioned in 10 interviews with strong emotional language has higher estimated impact than one mentioned once. + +**Effort estimation:** Get a rough engineering estimate -- not a detailed plan, but a t-shirt size (days, weeks, months). Include design, engineering, and validation effort. + +**Common mistake:** Teams consistently underestimate effort and overestimate impact. Build in a skepticism factor: if you think it's "medium effort," it's probably "high effort." + +### When to Use Impact vs. Effort + +| Good Use Case | Poor Use Case | +|---------------|---------------| +| Quick triage of a long list of opportunities | Final decision on a major strategic bet | +| Sprint planning: choosing between several well-understood small items | Quarterly planning: choosing between fundamentally different directions | +| Identifying quick wins to build momentum | Prioritizing when evidence quality varies widely | + +## Using Data to Prioritize + +Quantitative data strengthens prioritization by grounding estimates in reality rather than intuition. + +### Data Sources for Prioritization + +| Data Source | What It Tells You | Prioritization Use | +|-------------|-------------------|-------------------| +| **Usage analytics** | How many users encounter a particular workflow | Estimate opportunity reach | +| **Funnel analysis** | Where users drop off in a process | Identify high-severity pain points | +| **Support tickets** | What problems users report most often | Frequency and severity signals | +| **NPS/CSAT verbatims** | What customers mention as positives and negatives | Opportunity framing in customer language | +| **Cohort analysis** | How behavior differs between retained and churned users | Identify opportunities that drive retention | +| **Competitive intelligence** | What competitors are investing in | Signal market-level opportunity size | + +### Combining Qualitative and Quantitative + +Neither data type alone is sufficient. Use them together: + +| Qualitative (Interviews) | Quantitative (Data) | Combined Insight | +|--------------------------|---------------------|-----------------| +| "I struggle with search" (3 users) | 70% of active users use search daily | High-reach opportunity with validated pain | +| "Onboarding was confusing" (5 users) | 60% drop-off at project creation step | High-severity opportunity at a critical moment | +| "I'd love a mobile app" (2 users) | 5% of usage comes from mobile browsers | Low-reach opportunity despite vocal advocates | +| "I wish I could share with clients" (1 user) | No data yet | Needs more interviews before prioritizing | + +**Rule:** Let qualitative data tell you what the opportunity is. Let quantitative data tell you how big it is. + +## Avoiding Analysis Paralysis + +The most common failure mode in prioritization is not choosing poorly -- it's not choosing at all. Teams get stuck in endless analysis, waiting for more data, debating criteria, and deferring decisions. + +### Signs of Analysis Paralysis + +- The team has been "prioritizing" for more than two sessions without a decision +- Every opportunity has roughly equal scores and the team can't break the tie +- The team keeps asking for "one more interview" or "one more data point" before deciding +- No opportunities have been committed to for more than two weeks + +### How to Break Free + +**1. Time-box the decision:** "We will commit to our top opportunity by end of day Friday. Period." + +**2. Lower the stakes:** Remind the team that this is not an irreversible decision. You can switch opportunities as new evidence emerges. The cost of delay is higher than the cost of a suboptimal choice. + +**3. Use the "regret minimization" test:** "If we spend the next 6 weeks on this opportunity and it doesn't pan out, would we regret it? Or would we say 'we learned something valuable'?" + +**4. Default to evidence:** When opinions are split, ask: "Which opportunity has the most supporting evidence from interviews?" Default to the better-evidenced choice. + +**5. Start with assumption testing:** If you truly can't decide between two opportunities, don't build either one yet. Instead, test the riskiest assumption for each and let the test results break the tie. + +## When to Pivot Between Opportunities + +Committing to an opportunity doesn't mean ignoring new evidence. Here's when to revisit: + +| Signal | What It Means | Action | +|--------|---------------|--------| +| Assumption tests consistently fail | The opportunity may be smaller or different than expected | Re-examine the opportunity framing; consider pivoting | +| New interviews reveal a bigger opportunity | The landscape has changed | Add to the OST; run a comparison against current focus | +| Target outcome isn't moving despite shipping solutions | The opportunity may not be the right lever | Check if the opportunity is truly connected to the outcome | +| The team has exhausted solution ideas | Diminishing returns on the current opportunity | Move to the next-highest-priority opportunity | +| External change (market, competitor, regulation) | The priority landscape has shifted | Re-run prioritization with the new context | + +### Pivot vs. Persevere Framework + +Before pivoting, ask: +1. **Have we actually tested assumptions, or did we jump to building?** If you didn't test, go back and test. +2. **Did we give the solution enough time to show results?** Some solutions need weeks of adoption before impact appears. +3. **Is the evidence pointing consistently in one direction?** One failed test isn't enough; a pattern of failures is. +4. **What would we learn by spending one more week here?** If the answer is "nothing new," it's time to pivot. + +## Prioritization Cadence + +### Weekly + +- Review test results and how they affect current opportunity ranking +- Quick check: is the team still working on the highest-priority opportunity? + +### Monthly + +- Full prioritization review with updated evidence +- Add new opportunities discovered through recent interviews +- Remove or de-prioritize opportunities that have been addressed or invalidated + +### Quarterly + +- Strategic review of the outcome itself -- is this still the right outcome? +- Major re-prioritization aligned with company goals +- Stakeholder alignment on opportunity ranking + +## Communicating Priorities to Stakeholders + +### What Stakeholders Need to See + +| Audience | Format | Focus | +|----------|--------|-------| +| Executive leadership | OST summary with top 3 opportunities highlighted | Strategy and alignment with company goals | +| Cross-functional partners | Opportunity ranking with evidence summary | What to expect from the product team | +| Engineering team | Current opportunity + solutions with effort estimates | What to build and why | + +### Handling Stakeholder Requests + +When a stakeholder requests a feature that doesn't align with current priorities: + +1. **Acknowledge the request:** "Thank you -- this is worth considering" +2. **Map it to the OST:** "Let me see which opportunity this serves" +3. **Show the tradeoff:** "Pursuing this would mean deprioritizing [current focus], which is supported by [evidence]. Here's what we'd give up." +4. **Offer alternatives:** "If the underlying need is [X], here's how we're addressing it through [current opportunity]" + +This approach respects the stakeholder's input while keeping the team focused on evidence-based priorities. diff --git a/.agents/skills/create-app/SKILL.md b/.agents/skills/create-app/SKILL.md new file mode 100644 index 00000000..5ed8d58f --- /dev/null +++ b/.agents/skills/create-app/SKILL.md @@ -0,0 +1,242 @@ +--- +name: create-app +description: 'Guided journey from a raw app idea to a validated, cleanly architected first version that ships on a sustainable cadence. Orchestrates ten skills phase by phase - lean-startup, design-sprint, clean-architecture, domain-driven-design, clean-code, pragmatic-programmer, system-design, ios-hig-design, 37signals-way, software-design-philosophy - asking the user questions at every decision point and recording results in the project docs/ folder (PRODUCT.md, ARCHITECTURE.md, EXPERIMENTS.md, CREATE-APP-PLAN.md) so the journey resumes across sessions. Use when the user wants to build a new app, validate an idea before writing code, architect an MVP that will not need a rewrite, or says ''help me build my app the right way''. App already exists: use improve-app or grow-app. Business idea not yet validated: run create-business first. Marketing site only: use create-website. Architecture-only question: design-code-architecture. For one framework in isolation, invoke that skill directly.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# Create an App + +Take a raw app idea to a validated, cleanly architected first version that ships on a sustainable cadence — without over-building for scale you have not earned, or writing a prototype that calcifies into a rewrite. This journey runs ten phases: it asks before every decision and records each choice in `docs/` so you can stop and resume across sessions. The early phases often produce no code at all; once an experiment greenlights building, the engineering phases build the real thing well. + +## Core Principle + +**Validate fast while keeping options open: make the expensive-to-reverse decisions early and defer everything cheap.** Spend scarce early effort on the few things that compound — the riskiest assumption, the dependency boundaries, the domain language — and aggressively avoid waste everywhere else. + +This skill sequences the phases, asks the questions, and records the decisions; the constituent skills carry the method. Invoke them rather than improvising their frameworks. + +## Journey Map + +| Phase | Skill | Question it answers | Artifact | +|---|---|---|---| +| 1 | lean-startup | Is the riskiest assumption true, and what is the MVP? | Creates docs/PRODUCT.md + docs/EXPERIMENTS.md | +| 2 | design-sprint | What should the core flow be? | Creates docs/DESIGN.md, extends docs/EXPERIMENTS.md — awaiting-evidence | +| 3 | clean-architecture | What boundaries keep options open? | Creates docs/ARCHITECTURE.md | +| 4 | domain-driven-design | What does the code mean? | Extends docs/ARCHITECTURE.md | +| 5 | clean-code | Is each function readable and tested? | Creates docs/TESTING.md | +| 6 | pragmatic-programmer | Which habits keep it healthy? | Extends docs/TESTING.md + docs/TECH-DEBT.md | +| 7 | system-design | How big must it really be? | Extends docs/ARCHITECTURE.md | +| 8 | ios-hig-design | Does it feel native on iOS? | Extends docs/DESIGN.md — iOS only | +| 9 | 37signals-way | What ships, and what is cut? | Extends docs/PRODUCT.md + docs/STRATEGY.md | +| 10 | software-design-philosophy | Where is complexity hiding? | Extends docs/TECH-DEBT.md + docs/ARCHITECTURE.md | + +## Operating Rules + +1. **Resume first.** Before anything else, read `docs/CREATE-APP-PLAN.md` and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted. +2. **Intake on first run only.** No tracker: run the Intake below, then create `docs/CREATE-APP-PLAN.md` with every phase statused `pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason`. Done when the tracker exists and the user has confirmed the phase plan. +3. **Phase entry.** Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase `in-progress` on proceed. Done when the user chose. +4. **Skill invocation and fallback.** Invoke the phase's skill by its slug. If it is not available, offer: `npx skills add wondelai/skills/ --global`. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in. +5. **In-phase decisions.** Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect. +6. **Phase exit.** Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows `done`. +7. **Artifact discipline.** Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in `docs/`. Every recommendation lands as a checkbox or a table row with owner and priority. See [references/artifact-templates.md](references/artifact-templates.md) when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names. +8. **The agent prepares and processes; only the human talks to customers and test users.** Draft sprint scripts and interview guides and score the results, then pause with status `awaiting-evidence` until the user returns with notes. The ios-hig-design phase applies only when shipping a native iOS app; skip it otherwise at intake. + +## Intake + +Ask these before creating the tracker: + +1. What is the app idea in one sentence, and what is the riskiest belief behind it? (Gates Phase 1; if the job the app is hired for is fuzzy, add the jobs-to-be-done optional phase.) +2. Is the underlying idea already validated with behavioral evidence, or still a hunch? (Unvalidated and high-stakes makes Phase 1 mandatory; if paying customers already exist you may be in the wrong journey — improve-app or grow-app.) +3. What is the stage — weekend prototype, funded build toward launch, or a team forming around it? (A prototype leans on Phases 1-3 and 10; a forming team may add inspired-product.) +4. Will you ship a native iOS client? (Yes keeps Phase 8; no skips it.) +5. Do you have customers to talk to, or must you find them? (Gates the human evidence loop in Phases 1-2 and optional mom-test / continuous-discovery.) +6. What load do you expect in the first months — daily active users and actions per day? (Feeds Phase 7 capacity math and stops premature scaling.) +7. Solo build or team, and who owns shipping cadence? (Gates Phase 9 shaping.) + +Phase-skip heuristics: skip Phase 2 when the core flow is already tested or trivial; skip Phase 8 unless shipping native iOS; skip Phase 7 only when load is obviously tiny — but still record the estimate; for a weekend prototype, run Phases 3-6 as one pass but never skip the Dependency Rule. + +Then create `docs/CREATE-APP-PLAN.md` from the template with every phase statused, marking Phase 8 iOS-conditional. Done when `docs/CREATE-APP-PLAN.md` exists with every phase statused and the user has confirmed the plan. + +## Phases + +### Phase 1 — Validate the riskiest assumption (lean-startup) + +**Purpose:** Prove the belief that would kill the app if false — before writing production code. + +**Brief (fallback):** Plan Build-Measure-Learn backward: what must you learn, how will you know, what is the smallest build that finds out. Rank leap-of-faith assumptions by what is fatal, not what is easy to test. An MVP is a learning vehicle, often crude (Dropbox validated with a video, not a sync engine). Climb the validation ladder — signups weak, paid deposit strong, active usage strongest; aim for behavioral level 4-5, never "would you use this?" opinion. + +**Invoke:** `lean-startup` with the idea and, if CUSTOMER.md exists, the job statement. Ask for ranked leap-of-faith assumptions, the single smallest experiment that falsifies the riskiest, and a pre-committed behavioral success threshold. + +**Decide with the user:** Which assumption is fatal if false? Which experiment type — smoke test (demand), concierge (value), Wizard of Oz (automation)? What go/pivot threshold, fixed before running? Only the user runs it with real people; then pause `awaiting-evidence`. + +**Artifact:** Create docs/PRODUCT.md with `## Vision` and `## MVP Definition`; create docs/EXPERIMENTS.md with `## Experiment Cards` (EXP-001 with hypothesis, metric, decision rule) and `## Experiment Backlog`. Update the tracker. + +**Done when:** the fatal assumption is named, EXP-001 has a pre-committed threshold, PRODUCT.md states the MVP scope, and the user has the experiment to run. + +### Phase 2 — De-risk the core experience (design-sprint) + +**Purpose:** Settle what the core flow should be with a tested facade, before committing engineering time. + +**Brief (fallback):** Five days: Map the problem Monday, Sketch Tuesday, Decide Wednesday, Prototype Thursday, Test with five real users Friday. Output is a high-fidelity facade plus evidence, not code. The riskiest moment is a stranger's first ten minutes — test whether they understand it and finish the core task with no explanation. Five users surface the patterns; you need patterns, not significance. Never explain the prototype; watch where they get stuck. + +**Invoke:** `design-sprint` with the MVP scope from PRODUCT.md. Ask for a Monday map and How Might We reframes, a winning concept storyboard, and a five-act interview script with a note-taking grid (checkmark / cross / tilde per participant). Record the approved script under the sprint card in docs/EXPERIMENTS.md when pausing, so it survives the session break. + +**Decide with the user (on return):** Does the tested flow work as-is, need a reshape, or expose a demand problem that loops back to Phase 1? Which confusions become fixes? + +**Artifact:** Create docs/DESIGN.md with `## Design Direction`; extend docs/EXPERIMENTS.md `## Experiment Cards` with the sprint test and its verdict. Update the tracker. + +**Done when:** DESIGN.md records the direction, the sprint result and verdict are in EXPERIMENTS.md, and the user chose proceed / reshape / loop. + +### Phase 3 — Draw the boundaries (clean-architecture) + +**Purpose:** Isolate business rules so the database, framework, and providers stay swappable details. + +**Brief (fallback):** Source code dependencies point inward — frameworks toward use cases toward entities. Business rules must not import the framework or ORM. Use cases define interfaces (e.g. InvoiceRepository); infrastructure implements them; controllers translate an HTTP request into a plain request object and receive a plain response — no framework type crosses the boundary. Diagnostic: can you test the business rules with no database, web server, or framework running? Four circles are typical, not sacred — draw boundaries only at points of volatility. + +**Invoke:** `clean-architecture` with the validated MVP scope from PRODUCT.md. Ask for the layer map, the core use case with its request/response models, and the repository interfaces it depends on. + +**Decide with the user:** Where are the real volatility boundaries (database, third-party APIs, delivery mechanism)? Full four layers, or collapse adapters and frameworks for a small app? + +**Artifact:** Create docs/ARCHITECTURE.md with `## System Context` and `## Layer Map & Dependency Rule` (layers, what depends on what, a violations table). Update the tracker. + +**Done when:** ARCHITECTURE.md names the layers, the Dependency Rule direction is explicit, and the core business rule is testable with no infrastructure. + +### Phase 4 — Model the domain (domain-driven-design) + +**Purpose:** Make the code speak the business so a domain expert could read it and spot what is wrong. + +**Brief (fallback):** The model is the code. Build a Ubiquitous Language — name things after domain concepts, not technical roles (an `InvoiceDraft.finalize()` beats a `DataProcessor.process()`); hard-to-name is a design signal. Bounded contexts: a word means one thing inside a boundary ("Customer" in billing need not equal "Customer" in support). Aggregates: a cluster with one root that enforces invariants — keep them small, reference other aggregates by ID. Avoid the anemic model; push behavior into entities and value objects. + +**Invoke:** `domain-driven-design` with ARCHITECTURE.md's layer map. Ask for the ubiquitous language, the bounded contexts and context map, and the core aggregate with the invariants its root enforces. + +**Decide with the user:** What is the core domain (your competitive edge) versus generic subdomains (auth, email, payments) to buy or use open source? Where does the same word legitimately mean different things across contexts? + +**Artifact:** Extend docs/ARCHITECTURE.md: add `## Bounded Contexts & Context Map` and `## Domain Glossary (Ubiquitous Language)` (term | meaning | code name). Update the tracker. + +**Done when:** the glossary names the core concepts, contexts and relationships are mapped, and the repository interface sits in the domain layer per Phase 3. + +### Phase 5 — Write code to be read (clean-code) + +**Purpose:** Keep every function readable and tested as the codebase grows. + +**Brief (fallback):** Code is read far more than written. Small functions that do one thing at a single level of abstraction; intention-revealing names; no flag arguments (a smell — the function does two things); commands separate from queries; a well-named extracted function beats a comment. Tests are first-class — dirty tests are worse than none. Write them F.I.R.S.T. (Fast, Independent, Repeatable, Self-validating, Timely) with behavior-based names like shouldRejectNegativeTotal. + +**Invoke:** `clean-code` with the core module from Phases 3-4. Ask for a score-and-fix review against the rules and clean unit tests (arrange-act-assert, descriptive names, a builder helper) for the core use case. + +**Decide with the user:** What quality bar gates a commit — function size, name clarity, no swallowed exceptions? Which happy-path and failure cases must the first tests cover? + +**Artifact:** Create docs/TESTING.md with `## Test Strategy` (pyramid, tooling, what green gates) and `## Safety Net Map` (module | pinned behaviors | test files | gaps). Update the tracker. + +**Done when:** TESTING.md states the strategy, the core use case has passing behavior-named tests that need no database, and the commit quality bar is recorded. + +### Phase 6 — Install the meta-disciplines (pragmatic-programmer) + +**Purpose:** Adopt the habits that keep the codebase easy to change over years. + +**Brief (fallback):** Fire a tracer bullet — one thin real slice through every layer (UI to use case to database and back), kept, to surface integration bugs on day two. DRY applies to knowledge only, not coincidental similarity. Orthogonality: changing the database must not touch the UI. Reversibility: wrap third-party SDKs behind your own interfaces so Stripe or a model provider swaps without touching business logic. Broken windows: fix the first hack or board it up with a tracked ticket — never leave silent rot. + +**Invoke:** `pragmatic-programmer` with ARCHITECTURE.md and the core use case. Ask for the thinnest end-to-end tracer-bullet design and an adapter interface for each third-party dependency. + +**Decide with the user:** What is the tracer-bullet slice? Is the broken-windows policy zero-tolerance with tracked tickets? Which dependencies get adapter interfaces now versus later? + +**Artifact:** Extend docs/TESTING.md (`## CI Gates`) and docs/TECH-DEBT.md (`## Debt Budget & Broken-Windows Policy` and `## Adopted Conventions`). Update the tracker. + +**Done when:** the tracer bullet is specified end-to-end, adapter interfaces are named for each provider, and the broken-windows policy is written down. + +### Phase 7 — Size it honestly (system-design) + +**Purpose:** Estimate the real load and prove what you do NOT need to build yet. + +**Brief (fallback):** Start from requirements, not solutions. QPS = daily active users x actions/day / 86,400, peak 2-5x average; storage = records/day x record size x retention. For a few hundred users the math almost always says one well-indexed database plus a cache. Scale in order: vertical first, then read replicas, then cache aside, shard last. Reach for a queue to absorb spikes and decouple slow work (e.g. photo OCR) from the request path only when an estimate or real bottleneck justifies it. + +**Invoke:** `system-design` with the load numbers from intake. Ask for a back-of-the-envelope QPS and storage estimate and an explicit list of techniques you do NOT need yet. + +**Decide with the user:** Given the estimate, which scaling do you deliberately defer? Which real bottleneck, if any, justifies a cache or queue now? + +**Artifact:** Extend docs/ARCHITECTURE.md: add `## Data & Storage Decisions` and `## Decision Log` (date | decision | why | alternatives rejected), recording each "not yet" as a decision. Update the tracker. + +**Done when:** the capacity estimate is recorded, the deferred scaling techniques are listed explicitly, and any cache or queue is justified by a number. + +### Phase 8 — Make it feel native (ios-hig-design) — iOS only + +**Purpose:** Make an iPhone client feel native — the basis of iOS users' trust. Run only when shipping a native iOS client (decided at intake); skip otherwise. + +**Brief (fallback):** Three pillars — clarity, deference, depth. Respect safe areas (Dynamic Island, home indicator); every touch target at least 44x44 pt; semantic colors (Color(.label), Color(.systemBackground)) so Dark Mode is automatic; semantic text styles for Dynamic Type; native navigation — tab bars for primary destinations, NavigationStack for drill-down, sheets for focused tasks, never a hamburger menu. Accessibility is first-class: a label on every control, and VoiceOver can complete every task. + +**Invoke:** `ios-hig-design` with the app's key screens. Ask for a HIG review of safe areas, 44pt targets, semantic colors and type, native navigation, and accessibility labels. + +**Decide with the user:** Which screens are in scope for the first review? Any deliberate platform deviations, and are they justified? + +**Artifact:** Extend docs/DESIGN.md: add `## Components` (component | decision | status) and `## UX Audit Findings` (issue | heuristic | severity 0-4 | fix | status). Update the tracker. + +**Done when:** each in-scope screen is reviewed, findings are logged with severity, and accessibility gaps are captured as fixes. + +### Phase 9 — Ship on a cadence (37signals-way) + +**Purpose:** Ship a focused v1 on fixed time that fights feature creep. + +**Brief (fallback):** Build half a product, not a half-assed one. Shape work before betting it: rough enough for design freedom, solved enough to remove big unknowns, bounded by an appetite ("this is worth two weeks") — not an estimate. Fix the time and cut scope to fit, never the reverse. Bet shaped pitches into fixed cycles; a circuit breaker kills anything unfinished at the deadline. Opinionated software: every preference offered is a decision refused — pick sensible defaults; the default answer to a feature is a respectful "not now". + +**Invoke:** `37signals-way` with the MVP scope from PRODUCT.md. Ask for the next feature shaped into a pitch (problem, appetite, breadboard, rabbit holes, no-gos) and a v1 cut list. + +**Decide with the user:** What is the appetite for the next feature? Which v1 features get cut, and which user-facing preferences become opinionated defaults? + +**Artifact:** Extend docs/PRODUCT.md (`## Outcome Roadmap`) and docs/STRATEGY.md (`## No-List` — what we explicitly will not do). Update the tracker. + +**Done when:** the next feature has a shaped pitch with an appetite, the v1 cut list is in STRATEGY.md's No-List, and the roadmap reflects fixed-time / flexible-scope. + +### Phase 10 — Treat complexity as the enemy (software-design-philosophy) + +**Purpose:** Hold complexity down across every module — the lens over all the other phases. + +**Brief (fallback):** Complexity is anything about structure that makes a system hard to understand and change. Prefer deep modules — powerful functionality behind a simple interface — over shallow ones; judge a module by functionality divided by interface complexity, not line count. This corrects Clean Code's "small" and DDD's many concepts tipping into classitis (swarms of one-method shallow classes). Strategic over tactical: invest a steady 10-20% extra on design, because early shortcuts compound exactly as the team and codebase grow. + +**Invoke:** `software-design-philosophy` with the modules from Phases 3-6. Ask for a deep-vs-shallow evaluation flagging shallow classes, pass-through methods, and information leaking across boundaries, plus where to consolidate. + +**Decide with the user:** Which shallow modules should merge into deeper ones? Where is tactical shortcutting accruing debt worth the strategic 10-20% now? + +**Artifact:** Extend docs/TECH-DEBT.md (`## Smell Inventory`: smell | location | refactoring | status) and docs/ARCHITECTURE.md (`## Decision Log`). Update the tracker. + +**Done when:** shallow modules and leaks are logged in the Smell Inventory, consolidation decisions are recorded, and the strategic-vs-tactical stance is agreed. + +## Optional Phases + +| Skill | Add when | Artifact | +|---|---|---| +| jobs-to-be-done | the job the app is hired for is fuzzy or contested | Creates docs/CUSTOMER.md | +| mom-test | assumptions need customer conversations, not opinions | Extends docs/CUSTOMER.md | +| lean-ux | the team wants hypothesis-driven UX instead of heavy specs | Extends docs/EXPERIMENTS.md | +| ux-heuristics | the first usable build needs a usability pass | Extends docs/DESIGN.md | +| hooked-ux | the product depends on habitual repeat usage | Extends docs/PRODUCT.md | +| design-everyday-things | core flows confuse test users | Extends docs/DESIGN.md | +| continuous-discovery | post-launch, to keep weekly customer contact | Extends docs/CUSTOMER.md | +| inspired-product | a team forms around the product and needs vision and outcome roadmaps | Extends docs/PRODUCT.md | + +Optional phases follow the same operating rules; insert where the Add-when condition first becomes true. + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Building the architecture before validating the idea | Run Phase 1 first — validation is cheap, a rewrite is not (`lean-startup`). | +| Treating "MVP" as a license to write garbage | Ship the smallest thing to learn, then build the real thing well once greenlit; minimum is not low quality (`lean-startup`). | +| Letting the framework dictate the architecture | Keep frameworks in the outer ring as plugins; no ORM types cross use-case boundaries (`clean-architecture`). | +| The anemic domain model | Push behavior into entities and value objects, not fat service classes (`domain-driven-design`). | +| Classitis — over-applying "small" | Judge modules by depth (functionality per unit of interface), not line count (`software-design-philosophy`). | +| Premature scaling | Do the estimate; one database plus a cache carries most apps far — shard last (`system-design`). | + +## Completing the Journey + +Exit checklist: + +- [ ] PRODUCT.md states a validated MVP and vision; EXPERIMENTS.md holds a run experiment with a recorded verdict. +- [ ] ARCHITECTURE.md passes the Dependency Rule test and names the core domain, contexts, and capacity estimate. +- [ ] TESTING.md shows the core use case tested with no infrastructure and the tracer bullet running end-to-end. +- [ ] STRATEGY.md's No-List and a shaped next feature exist if shipping continues. + +Close the tracker: every phase `done` or `skipped: reason`, Key Decisions captured, and Next Actions carried into the artifacts (not left in the tracker). Forward routing: + +- When the idea underneath the app turns out to be unvalidated, or is really a commercial-model question, continue with `create-business`. +- When the app grows past its first architecture and the structure itself becomes the hard problem, continue with `design-code-architecture`. diff --git a/.agents/skills/create-app/references/artifact-templates.md b/.agents/skills/create-app/references/artifact-templates.md new file mode 100644 index 00000000..d0e1f80d --- /dev/null +++ b/.agents/skills/create-app/references/artifact-templates.md @@ -0,0 +1,154 @@ +# create-app artifact templates + +Skeletons this metaskill creates in the user's docs/ folder. Extend-only artifacts (CUSTOMER.md, STRATEGY.md, TECH-DEBT.md) are governed by the section headings named in each phase, not skeletons here. + +## docs/CREATE-APP-PLAN.md (tracker) + +```markdown +# Create an App Plan + +## Context +Intake answers, date started, project specifics. Note whether shipping native iOS (gates Phase 8). + +## Phase Status +| Phase | Skill | Status | Artifact | Date | +|---|---|---|---|---| +| 1 | lean-startup | pending | PRODUCT.md, EXPERIMENTS.md | | +| 2 | design-sprint | pending | DESIGN.md, EXPERIMENTS.md | | +| 3 | clean-architecture | pending | ARCHITECTURE.md | | +| 4 | domain-driven-design | pending | ARCHITECTURE.md | | +| 5 | clean-code | pending | TESTING.md | | +| 6 | pragmatic-programmer | pending | TESTING.md, TECH-DEBT.md | | +| 7 | system-design | pending | ARCHITECTURE.md | | +| 8 | ios-hig-design | pending | DESIGN.md | | +| 9 | 37signals-way | pending | PRODUCT.md, STRATEGY.md | | +| 10 | software-design-philosophy | pending | TECH-DEBT.md, ARCHITECTURE.md | | +Statuses: pending · in-progress · awaiting-evidence · done · deferred: · skipped: + +## Key Decisions +| Date | Phase | Decision | Rationale | +|---|---|---|---| + +## Next Actions +- [ ] action (owner, due) +``` + +## docs/PRODUCT.md + +```markdown +# Product + +## Vision +One paragraph. + +## MVP Definition +Type, scope, what it deliberately excludes. + +## Outcome Roadmap +| Outcome / problem | Job served | Priority | Status | +|---|---|---|---| + +## Opportunity Solution Tree Notes + +## Hook Model +Trigger → Action → Variable reward → Investment; weakest phase. + +## Activation & Retention Plan +| Friction / moment | Fix | Owner | Status | +|---|---|---|---| + +## Discovery Cadence +Weekly touchpoint plan. +``` + +## docs/EXPERIMENTS.md + +```markdown +# Experiments + +## Experiment Cards +### EXP-001 — [name] +- Hypothesis: We believe [outcome] if [who] [does what] because [reason] +- Type: sprint / smoke test / concierge / painted door / A-B +- Primary metric & threshold (pre-committed): +- Guardrail metric: +- Decision rule (pivot / persevere / iterate): +- Result & verdict: + +## Experiment Backlog +| Idea | ICE (impact/confidence/ease) | Status | +|---|---|---| +``` + +## docs/ARCHITECTURE.md + +```markdown +# Architecture + +## System Context +What the system does, key integrations, load reality (back-of-envelope numbers). + +## Layer Map & Dependency Rule +Layers, what depends on what, current violations. +| Violation | Location | Fix | Status | +|---|---|---|---| + +## Bounded Contexts & Context Map +Contexts, relationships, anti-corruption layers. + +## Domain Glossary (Ubiquitous Language) +| Term | Meaning | Code name | +|---|---|---| + +## Data & Storage Decisions +Data models, storage engines, isolation levels, replication, system-of-record vs derived data. + +## Decision Log +| Date | Decision | Why | Alternatives rejected | +|---|---|---|---| +``` + +## docs/TESTING.md + +```markdown +# Testing + +## Test Strategy +Pyramid, tooling, what "green" gates. + +## Safety Net Map +| Module | Pinned behaviors | Test files | Gaps | +|---|---|---|---| + +## Characterization Backlog +- [ ] module (risk, priority) + +## CI Gates +``` + +## docs/DESIGN.md + +```markdown +# Design System + +## Design Direction +Signature moment, personality, references. + +## Typography +Typefaces, scale, measure, line height, loading strategy. + +## Tokens +Spacing scale · color palette (shades, tinted grays) · shadows. + +## Components +| Component | Decision | Status | +|---|---|---| + +## UX Audit Findings +| Issue | Heuristic | Severity (0-4) | Fix | Status | +|---|---|---|---|---| + +## Microinteraction Inventory +| Interaction | Trigger/Rules/Feedback/Loops | Fix | Status | +|---|---|---|---| +``` diff --git a/.agents/skills/create-business/SKILL.md b/.agents/skills/create-business/SKILL.md new file mode 100644 index 00000000..127efde8 --- /dev/null +++ b/.agents/skills/create-business/SKILL.md @@ -0,0 +1,234 @@ +--- +name: create-business +description: 'Guided journey from raw idea to a validated, positioned, priced business with a chosen beachhead. Orchestrates ten skills phase by phase - jobs-to-be-done, mom-test, design-sprint, lean-startup, good-strategy-bad-strategy, blue-ocean-strategy, obviously-awesome, hundred-million-offers, monetizing-innovation, crossing-the-chasm - asking the user questions at every decision point and recording results in the project docs/ folder (CUSTOMER.md, POSITIONING.md, OFFER.md, CREATE-BUSINESS-PLAN.md) so the journey resumes across sessions. Use when the user wants to start a new business, validate a startup idea, find product-market fit before building, or says ''I have an idea for a company''. Do not use once the business has paying customers: use grow-business to add revenue and customers, or improve-business to fix strategy and operations. For building the product itself use create-app or create-website. For one framework in isolation, invoke that skill directly.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# Create a Business + +Take a raw idea to a business you can defend on every axis: who it is for, what job it does, why it is different, why it wins, what it costs, and why anyone would pay. This journey runs ten phases in sequence, looping back as evidence accumulates. It is interactive — the agent asks before every decision — and resumable: all state lives in `docs/` so you can stop and restart across sessions. The order is the point: demand before building, strategy before scale, price before product. + +## Core Principle + +**Earn your evidence before you spend your runway: demand before building, strategy before scale, price before product.** You can be wrong about your product in a week, or wrong about your business in a year — pick the week. This skill sequences the phases, asks the questions at every decision point, and records what you decide in `docs/`. The constituent skills carry the method — invoke them rather than improvising their frameworks. + +## Journey Map + +| Phase | Skill | Question it answers | Artifact | +|---|---|---|---| +| 1 | jobs-to-be-done | What progress is the customer really hiring us for? | Creates docs/CUSTOMER.md | +| 2 | mom-test | Is the job real, painful, and worth paying to solve? | Extends docs/CUSTOMER.md — GATE | +| 3 | design-sprint | Does the concept survive contact with five real customers? | Creates docs/EXPERIMENTS.md | +| 4 | lean-startup | What is the smallest MVP that tests the riskiest assumption? | Creates docs/PRODUCT.md; extends docs/EXPERIMENTS.md | +| 5 | good-strategy-bad-strategy | What is the one critical challenge, and how do we win? | Creates docs/STRATEGY.md | +| 6 | blue-ocean-strategy | Where is the uncontested space we can own? | Extends docs/STRATEGY.md | +| 7 | obviously-awesome | What are we, and why does that matter, in 30 seconds? | Creates docs/POSITIONING.md | +| 8 | hundred-million-offers | What makes this offer impossible to refuse? | Creates docs/OFFER.md | +| 9 | monetizing-innovation | What will people actually pay, and per what? | Extends docs/OFFER.md | +| 10 | crossing-the-chasm | Which single segment do we dominate first? | Extends docs/STRATEGY.md | + +## Operating Rules + +1. **Resume first.** Before anything else, read `docs/CREATE-BUSINESS-PLAN.md` and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted. +2. **Intake on first run only.** No tracker: run the Intake below, then create `docs/CREATE-BUSINESS-PLAN.md` with every phase statused `pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason`. Done when the tracker exists and the user has confirmed the phase plan. +3. **Phase entry.** Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase `in-progress` on proceed. Done when the user chose. +4. **Skill invocation and fallback.** Invoke the phase's skill by its slug. If it is not available, offer: `npx skills add wondelai/skills/ --global`. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in. +5. **In-phase decisions.** Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect. +6. **Phase exit.** Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows `done`. +7. **Artifact discipline.** Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in `docs/`. Every recommendation lands as a checkbox or a table row with owner and priority. See [references/artifact-templates.md](references/artifact-templates.md) when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names. +8. **The agent prepares and processes; only the human talks to customers.** Draft interview guides and score transcripts, then pause with status `awaiting-evidence` until the user returns with notes. Never simulate a customer — a role-played interview confirms whatever you hope is true. + +## Intake + +Ask these before creating the tracker (skip any already answered): + +1. What is the raw idea, in one or two sentences? (seeds the job reconstruction in Phase 1) +2. Who do you imagine the customer is, and how do they solve this today? (feeds Competing Alternatives; a tight segment speeds Phases 7 and 10) +3. What customer access do you have — a list, a community, warm intros? (gates Phases 2-4; without access the human-only interview phases stall) +4. What evidence already exists — past interviews, a waitlist, sales, a prototype? (lets us fast-track or skip discovery already done) +5. Is this B2B or B2C — and if B2B, sales-led or self-serve? Is it a marketplace or network product? (routes optional predictable-revenue and cold-start-problem) +6. What is your runway and deadline? (sets phase depth and whether to defer strategy phases) +7. Is any product already built? (if so this may be the wrong journey — route to grow-business or improve-business) + +Phase-skip heuristics: skip Phase 1 when a validated job statement with three dimensions already exists in CUSTOMER.md; skip Phase 3 when a working prototype has already been tested with 5+ target users; defer Phase 6 for a clearly-differentiated niche until the kernel is set; defer Phases 5-10 until Phase 2 returns real commitments — no strategy on unvalidated demand. Then create `docs/CREATE-BUSINESS-PLAN.md` from the template, status every phase, and confirm the plan. Done when `docs/CREATE-BUSINESS-PLAN.md` exists with every phase statused and the user has confirmed the plan. + +## Phases + +### Phase 1 — Find the real job (jobs-to-be-done) + +**Purpose:** Reframe the raw idea as the progress a customer is trying to make, so the business survives even if the first solution dies. + +**Brief (fallback):** A job is progress in context, not a goal or a task — write it as `When [situation], I want to [motivation], so I can [outcome]`, solution-agnostic. Every job has functional, emotional, and social dimensions; the differentiated product usually lives in the last two. Real competition includes workarounds and non-consumption — name the hire you must beat. + +**Invoke:** `jobs-to-be-done` with the raw idea and customer guess from Intake. Ask for a When/I-want-to/so-I-can job statement, all three dimensions, and the full competing-alternatives set including non-consumption. + +**Decide with the user:** Which job statement is the real one, and which competing hire you must beat first. Recommend the tightest statement that still names an emotional or social dimension. + +**Artifact:** Create docs/CUSTOMER.md with `## Job Statement`, `## Job Dimensions`, and `## Competing Alternatives`. Update the tracker. + +**Done when:** CUSTOMER.md holds a solution-agnostic job statement, all three dimensions, and the competing set with the hire-to-beat named. + +### Phase 2 — Validate the job with real conversations (mom-test) — GATE + +**Purpose:** Replace opinions with facts — evidence the Phase 1 job is real, painful, and worth paying to solve. Phases 5-10 stay locked until this returns a proceed verdict. + +**Brief (fallback):** Three rules — talk about their life not your idea; ask about specifics in the past not hypotheticals; talk less (they speak 80%). Compliments are not data; only commitments (time, reputation, money) count. A good question could destroy the imagined business. + +**Invoke:** `mom-test` with the job statement and competing alternatives from docs/CUSTOMER.md. Ask for (a) a 10-12 question interview guide obeying the three rules, then later (b) transcript scoring that flags leading questions and zombie leads. Hand the guide to the user and pause with status `awaiting-evidence`; record the approved guide in docs/CUSTOMER.md under a `### Interview Guide` subsection of `## Interview Evidence` so it survives the pause. + +**Decide with the user (on return):** Does the evidence confirm the job? Proceed (3+ concrete commitments), revise the job statement (loop to Phase 1), or stop (no pain found — a cheap win). + +**Artifact:** Extend docs/CUSTOMER.md: add `## Interview Evidence` (date | who | facts | commitment) and `## Validation Verdict` with the decision and reasoning. Update the tracker. + +**Done when:** CUSTOMER.md holds 5+ evidence rows, the verdict is recorded, the user chose proceed / revise / stop, and — on proceed — Phases 5-10 are unlocked. + +### Phase 3 — Test the riskiest assumption in five days (design-sprint) + +**Purpose:** Before committing months, prove the riskiest part of the concept in one week with five real customer reactions. + +**Brief (fallback):** Five days — Map, Sketch, Decide, Prototype, Test. Pick one target moment (the riskiest step); sketch alone (no group brainstorms); a single Decider breaks ties; build a facade, not working code; test with exactly five target customers. On Friday, shut up and let them struggle — explaining the prototype invalidates the test. + +**Invoke:** `design-sprint` with the validated job and riskiest open question. Ask for the Monday map with sprint questions and target moment, and a Friday five-act interview script that does not explain the prototype. Hand the recruiting brief to the user and pause `awaiting-evidence` for real sessions; record the approved script and brief under the sprint card in docs/EXPERIMENTS.md so they survive the pause. + +**Decide with the user:** What single assumption to test this week and who is the Decider. On return: does the concept survive — build, fix, or walk away (a one-week win)? + +**Artifact:** Create docs/EXPERIMENTS.md with `## Experiment Cards` (EXP-001, type sprint, pre-committed metric, decision rule, result and verdict) and `## Experiment Backlog`. Update the tracker. + +**Done when:** EXPERIMENTS.md holds the sprint card with a recorded verdict from five sessions, and the user chose build / fix / walk away. + +### Phase 4 — Run the loop and pick the smallest MVP (lean-startup) + +**Purpose:** Turn discovery into a repeatable engine of validated learning and ship the smallest MVP that tests the riskiest leap-of-faith assumption. + +**Brief (fallback):** Plan Build-Measure-Learn backward: decide what to learn, then the metric that proves it, then the minimum build. MVP types — smoke test, concierge, Wizard of Oz — each test a different leap-of-faith assumption; test the riskiest first. Measure actionable metrics, not vanity ones. Set pivot-or-persevere criteria before running. Pick one engine of growth: sticky, viral, or paid. + +**Invoke:** `lean-startup` with the feature wish list and surviving concept. Ask for the single riskiest leap-of-faith assumption, an MVP type with a Build-Measure-Learn experiment card, and pivot-or-persevere thresholds set in advance. + +**Decide with the user:** Which MVP type, which single engine of growth to optimize first, and the pre-committed pivot/persevere thresholds. Recommend the sticky engine (retention above churn) before paid acquisition. + +**Artifact:** Create docs/PRODUCT.md with `## Vision` and `## MVP Definition`; extend docs/EXPERIMENTS.md with a new card and its decision rule. Update the tracker. + +**Done when:** PRODUCT.md defines the MVP and what it excludes, EXPERIMENTS.md holds the card with pre-committed thresholds and the chosen engine, and the user approved the MVP scope. + +### Phase 5 — Turn ambition into a strategy kernel (good-strategy-bad-strategy) + +**Purpose:** Replace a wish list of goals with a real strategy — a diagnosis, a guiding policy, and coherent actions. + +**Brief (fallback):** A goal names ambition; a strategy explains how you win given the obstacles. The kernel: a diagnosis naming the single critical challenge; a guiding policy that is a genuine choice with losers (if a rival could paste it in, it is a platitude); coherent actions, each with an owner and date. Detect bad strategy by the four hallmarks — fluff, dodging the challenge, goals-as-strategy, dog's-dinner objective lists. Concentrate force on one pivot point. + +**Invoke:** `good-strategy-bad-strategy` with the validated demand evidence and any one-page plan. Ask for a four-hallmarks audit, then a kernel — a one-paragraph diagnosis, a guiding policy that rules whole classes of action out, three coherent actions with owners — plus an explicit no-list. + +**Decide with the user:** What is the single critical challenge (the diagnosis), and what does the guiding policy explicitly refuse to do? Recommend concentrating on one pivot point over spreading thin. + +**Artifact:** Create docs/STRATEGY.md with `## Diagnosis`, `## Guiding Policy`, `## Coherent Actions`, and `## No-List`. Update the tracker. + +**Done when:** STRATEGY.md names one critical challenge, a guiding policy with losers, coherent actions with owners, and an explicit no-list. + +### Phase 6 — Find uncontested space (blue-ocean-strategy) + +**Purpose:** Choose where to win by creating uncontested space instead of fighting head-on on the same factors as everyone else. + +**Brief (fallback):** Value innovation pursues differentiation and low cost at once. The ERRC grid — Eliminate, Reduce, Raise, Create — lifts buyer value while cutting cost. Plot a strategy canvas: a different offering diverges from the industry curve. Blue oceans convert non-customers (soon-to-be, refusing, unexplored), not rivals' customers — find the common barrier to remove. Do not eliminate factors customers genuinely value (trust, security, accuracy). + +**Invoke:** `blue-ocean-strategy` with the competing alternatives from CUSTOMER.md and the kernel from STRATEGY.md. Ask for a strategy canvas of current factors and an ERRC grid for a value-innovation move within resource limits. + +**Decide with the user:** Which factors to eliminate / reduce / raise / create, and which tier of non-customers to convert first. Confirm no trust, security, or accuracy factor is being cut. + +**Artifact:** Extend docs/STRATEGY.md: add `## Strategy Canvas & ERRC Grid`. Update the tracker. + +**Done when:** STRATEGY.md holds a filled ERRC grid and a strategy canvas showing a divergent curve, with the target non-customer tier chosen. + +### Phase 7 — Position so prospects instantly get it (obviously-awesome) + +**Purpose:** Set the context that makes the product's strengths obvious within thirty seconds. + +**Brief (fallback):** Positioning is context, not messaging — customers judge you relative to alternatives, so choose the comparison. Five steps: true competitive alternatives (often a spreadsheet or doing nothing); unique attributes (pass the "only we" test); value via the "so what?" test; best-fit customers (tight, by title and firm traits, never everyone); market category (existing / subcategory / new — a new one pays an education tax). + +**Invoke:** `obviously-awesome` with unique attributes from STRATEGY.md and CUSTOMER.md. Ask for the full five-step exercise and an internal positioning statement: "For [best-fit customer], we are the [category] that [key value]." + +**Decide with the user:** Which market category to compete in (existing / subcategory / new) and who the best-fit customer is. Recommend existing or subcategory unless there is traction to spare for a new category. + +**Artifact:** Create docs/POSITIONING.md with `## Competitive Alternatives`, `## Unique Attributes → Value Themes`, `## Best-Fit Customer`, `## Market Category`, and `## One-Liner`. Update the tracker. + +**Done when:** POSITIONING.md holds the five-step canvas and a one-liner an outsider grasps in 30 seconds. + +### Phase 8 — Build an offer people feel stupid refusing (hundred-million-offers) + +**Purpose:** Turn understanding into buying with a Grand Slam Offer that makes price comparison impossible. + +**Brief (fallback):** The offer is the number one lever. Value = (dream outcome × perceived likelihood) / (time delay × effort) — maximize the top, minimize the bottom. Assemble a Grand Slam Offer: core offer, named bonuses (each kills an objection, each with a defensible value), a risk-reversing guarantee, ethical scarcity. Name it with MAGIC. Keep every value honest and every guarantee honorable. + +**Invoke:** `hundred-million-offers` with the positioning and best-fit customer from POSITIONING.md. Ask for a Grand Slam Offer built on the Value Equation, three named bonuses each killing an objection, a guarantee, ethical scarcity, and a MAGIC name. + +**Decide with the user:** Which dream outcome to anchor on and which objections the bonuses must kill. Confirm every dollar value and every scarcity claim is genuinely true — replace any tactic that would need invented evidence. + +**Artifact:** Create docs/OFFER.md with `## Offer Stack` (core · bonuses · guarantee · scarcity · name). Update the tracker. + +**Done when:** OFFER.md holds a complete offer stack with honest values, a real guarantee, and a name — no invented evidence. + +### Phase 9 — Price against validated willingness to pay (monetizing-innovation) + +**Purpose:** Design the product around the price by testing willingness to pay while it is still a concept. + +**Brief (fallback):** Customers reveal a range: ask what feels acceptable, expensive, prohibitive; trust only the top-box purchase probability. Avoid the four failures — feature shock, minivation (near-100% win rate with no pushback), hidden gem, undead. Segment by value and willingness to pay, never demographics. Package leader / filler / killer; design the middle tier first; pull killer features into add-ons. Choose the price metric before the price level. + +**Invoke:** `monetizing-innovation` with the offer from OFFER.md and segments from CUSTOMER.md. Ask for a willingness-to-pay interview script (acceptable / expensive / prohibitive), a leader/filler/killer classification, good-better-best tiers, and a price metric. Hand the WTP script to the user and pause `awaiting-evidence` for real calls; record the approved script in docs/OFFER.md under a `### WTP Interview Script` subsection of `## Willingness-to-Pay Evidence` so it survives the pause. + +**Decide with the user:** Which price metric to charge on (per seat / per unit of value) and the good-better-best tier boundaries. Recommend a metric that tracks delivered value so revenue compounds. + +**Artifact:** Extend docs/OFFER.md: add `## Willingness-to-Pay Evidence`, `## Leader / Filler / Killer Features`, `## Tiers (Good / Better / Best)`, and `## Price Metric`. Update the tracker. + +**Done when:** OFFER.md holds WTP evidence, feature classes, tiers with the middle designed first, and a price metric chosen before the level. + +### Phase 10 — Pick the beachhead you will dominate first (crossing-the-chasm) + +**Purpose:** Choose one narrow segment to dominate and assemble the whole product it needs to cross from visionaries to pragmatists. + +**Brief (fallback):** The chasm sits between visionary early adopters and pragmatist early majority — what wins one repels the other. Do not be everything to everyone: pick one narrow beachhead with urgent, expensive pain, reachable channels, customers who talk to each other, small enough to own yet big enough to matter. Assemble the whole product (integrations, onboarding, support, partners). References are the currency; shift positioning from "revolutionary" to "proven." + +**Invoke:** `crossing-the-chasm` with POSITIONING.md and STRATEGY.md. Ask to score candidate niches on pain, reachability, word-of-mouth, and dominability, then map the whole-product requirements a pragmatist needs before buying. + +**Decide with the user:** Which single beachhead segment to own first. Recommend the highest-scoring niche small enough to dominate; resist chasing several at once. + +**Artifact:** Extend docs/STRATEGY.md: add `## Beachhead` (target segment, scoring rationale) and `## Whole-Product Checklist` (each gap with owner and priority). Update the tracker. + +**Done when:** STRATEGY.md names one beachhead with scoring, and the whole-product checklist lists each gap with owner and priority. + +## Optional Phases + +| Skill | Add when | Artifact | +|---|---|---| +| storybrand-messaging | a website or pitch needs customer-as-hero copy before launch | Extends docs/POSITIONING.md | +| one-page-marketing | go-to-market planning starts before the beachhead phase closes | Creates docs/MARKETING.md | +| lean-analytics | the MVP is live and needs a first metrics baseline | Creates docs/METRICS.md | +| cold-start-problem | the product is a marketplace or network product | Extends docs/STRATEGY.md | +| predictable-revenue | B2B with a sales-led motion | Extends docs/MARKETING.md | +| continuous-discovery | post-launch, to make discovery a weekly habit | Extends docs/CUSTOMER.md | + +Optional phases follow the same operating rules; insert where the Add-when condition first becomes true. + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Building before validating | Buy evidence with the smallest MVP — smoke test or concierge — before writing real code; run Phases 1-4 first (lean-startup). | +| Pitching during discovery | Keep interviews about their life and past behavior; save the idea for the very end, if at all (mom-test). | +| Mistaking compliments and signups for validation | Chase commitments — a deposit, pre-order, scheduled pilot — and record them in CUSTOMER.md Interview Evidence. | +| Confusing goals for strategy | Write the diagnosis of the one critical challenge first; audit against the four hallmarks (good-strategy-bad-strategy). | +| Positioning for everyone | Tighten the best-fit definition until it is uncomfortably narrow, then go narrower (obviously-awesome). | +| Pricing on cost or competitors | Price from validated willingness-to-pay ranges and choose the price metric before the level (monetizing-innovation). | + +## Completing the Journey + +Exit checklist — every box tied to an artifact that must exist: + +- [ ] CUSTOMER.md holds a validated job statement and 5+ evidence rows with real commitments +- [ ] EXPERIMENTS.md shows the riskiest assumption tested with a recorded verdict +- [ ] STRATEGY.md has a kernel (diagnosis, guiding policy, coherent actions), a no-list, an ERRC grid, and a chosen beachhead with its whole-product checklist +- [ ] POSITIONING.md one-liner passes the 30-second outsider test +- [ ] OFFER.md holds a priced Grand Slam offer backed by willingness-to-pay evidence and a price metric + +Close the tracker: every phase `done` or `skipped: reason`, and any open Next Actions carried into the relevant artifacts. Forward routing: when the beachhead is chosen and first customers are paying, continue with `grow-business` to add revenue and customers. When the validated idea needs a software product built, continue with `create-app`. diff --git a/.agents/skills/create-business/references/artifact-templates.md b/.agents/skills/create-business/references/artifact-templates.md new file mode 100644 index 00000000..c963b9d0 --- /dev/null +++ b/.agents/skills/create-business/references/artifact-templates.md @@ -0,0 +1,202 @@ +# Artifact Templates — create-business + +Skeletons this metaskill creates in the user's `docs/` folder. Extend-only artifacts are governed by the section headings named in each phase. Read the file before writing; create only if missing, otherwise extend — add or update your own sections, preserve everyone else's. Headings are a cross-skill contract: do not rename or reorder them. + +## docs/CREATE-BUSINESS-PLAN.md (tracker) + +The Phase Status table is pre-filled with this journey's ten phases. + +```markdown +# Create a Business Plan + +## Context +Intake answers, date started, project specifics. + +## Phase Status +| Phase | Skill | Status | Artifact | Date | +|---|---|---|---|---| +| 1 Find the real job | jobs-to-be-done | pending | CUSTOMER.md | | +| 2 Validate the job | mom-test | pending | CUSTOMER.md | | +| 3 Test riskiest assumption | design-sprint | pending | EXPERIMENTS.md | | +| 4 Smallest MVP + BML loop | lean-startup | pending | PRODUCT.md, EXPERIMENTS.md | | +| 5 Strategy kernel | good-strategy-bad-strategy | pending | STRATEGY.md | | +| 6 Uncontested space | blue-ocean-strategy | pending | STRATEGY.md | | +| 7 Positioning | obviously-awesome | pending | POSITIONING.md | | +| 8 Grand Slam offer | hundred-million-offers | pending | OFFER.md | | +| 9 Pricing | monetizing-innovation | pending | OFFER.md | | +| 10 Beachhead | crossing-the-chasm | pending | STRATEGY.md | | +Statuses: pending · in-progress · awaiting-evidence · done · deferred: · skipped: + +## Key Decisions +| Date | Phase | Decision | Rationale | +|---|---|---|---| + +## Next Actions +- [ ] action (owner, due) +``` + +## docs/CUSTOMER.md + +Created in Phase 1, extended in Phase 2 (and optional continuous-discovery). + +```markdown +# Customer + +## Job Statement +When [situation], I want to [motivation], so I can [outcome]. + +## Job Dimensions +| Dimension | Description | +|---|---| +| Functional | | +| Emotional | | +| Social | | + +## Competing Alternatives +| Alternative (incl. non-consumption) | Why hired today | Weakness | +|---|---|---| + +## Interview Evidence +| Date | Who | Concrete facts (past behavior) | Commitment given | +|---|---|---|---| + +## Validation Verdict +Decision (proceed / revise / stop) and reasoning. + +## Segments & Best-Fit Customer +``` + +## docs/EXPERIMENTS.md + +Created in Phase 3, extended in Phase 4. + +```markdown +# Experiments + +## Experiment Cards +### EXP-001 — [name] +- Hypothesis: We believe [outcome] if [who] [does what] because [reason] +- Type: sprint / smoke test / concierge / painted door / A-B +- Primary metric & threshold (pre-committed): +- Guardrail metric: +- Decision rule (pivot / persevere / iterate): +- Result & verdict: + +## Experiment Backlog +| Idea | ICE (impact/confidence/ease) | Status | +|---|---|---| +``` + +## docs/PRODUCT.md + +Created in Phase 4. + +```markdown +# Product + +## Vision +One paragraph. + +## MVP Definition +Type, scope, what it deliberately excludes. + +## Outcome Roadmap +| Outcome / problem | Job served | Priority | Status | +|---|---|---|---| + +## Opportunity Solution Tree Notes + +## Hook Model +Trigger → Action → Variable reward → Investment; weakest phase. + +## Activation & Retention Plan +| Friction / moment | Fix | Owner | Status | +|---|---|---|---| + +## Discovery Cadence +Weekly touchpoint plan. +``` + +## docs/STRATEGY.md + +Created in Phase 5, extended in Phases 6 and 10 (and optional cold-start-problem). + +```markdown +# Strategy + +## Diagnosis +The single critical challenge. + +## Guiding Policy + +## Coherent Actions +| Action | Owner | Due | Status | +|---|---|---|---| + +## No-List +What we explicitly will not do. + +## Strategy Canvas & ERRC Grid +| Factor | Eliminate | Reduce | Raise | Create | +|---|---|---|---|---| + +## Beachhead +Target segment, scoring rationale. + +## Whole-Product Checklist +- [ ] gap (owner, priority) +``` + +## docs/POSITIONING.md + +Created in Phase 7 (Brand Script and Key Messages via optional storybrand-messaging). + +```markdown +# Positioning & Messaging + +## Competitive Alternatives + +## Unique Attributes → Value Themes +| Attribute | Value ("so what") | Proof | +|---|---|---| + +## Best-Fit Customer + +## Market Category +Choice (existing / subcategory / new) and rationale. + +## One-Liner + +## Brand Script (StoryBrand) +Character · Problem (external/internal/philosophical) · Guide · Plan · Call to action · Failure · Success. + +## Key Messages +| Surface | Message | Status | +|---|---|---| +``` + +## docs/OFFER.md + +Created in Phase 8, extended in Phase 9. + +```markdown +# Offer & Pricing + +## Offer Stack +| Element | Description | Honest value | Objection it kills | +|---|---|---|---| +Core offer · Bonuses · Guarantee · Scarcity/urgency (real only) · Name. + +## Willingness-to-Pay Evidence +| Segment | Acceptable | Expensive | Prohibitive | Source | +|---|---|---|---|---| + +## Leader / Filler / Killer Features +| Feature | Class | Tier placement | +|---|---|---| + +## Tiers (Good / Better / Best) + +## Price Metric +What we charge per, and why. +``` diff --git a/.agents/skills/create-website/SKILL.md b/.agents/skills/create-website/SKILL.md new file mode 100644 index 00000000..e09c0d95 --- /dev/null +++ b/.agents/skills/create-website/SKILL.md @@ -0,0 +1,234 @@ +--- +name: create-website +description: 'Guided journey from a blank page to a live, high-converting website, built message-first, then design, then conversion. Orchestrates ten skills phase by phase - one-page-marketing, storybrand-messaging, made-to-stick, top-design, web-typography, refactoring-ui, ux-heuristics, cro-methodology, scorecard-marketing, steve-jobs-design-review - asking the user questions at every decision point and recording results in the project docs/ folder (POSITIONING.md, WEBSITE.md, DESIGN.md, CREATE-WEBSITE-PLAN.md) so the journey resumes across sessions. Use when the user wants to build a new website or landing page from scratch, turn a validated idea into a page that converts, or says ''build me a landing page for my SaaS''. Site already exists: use improve-website to fix conversion/UX or grow-website for more traffic; building a software product, not a marketing site: use create-app; no positioning yet: run create-business first or the positioning phase here. For one framework in isolation, invoke that skill directly.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# Create a Website + +A blank page becomes a live, high-converting website through ten phases run in one dependency-respecting order: message, then design, then conversion, then a brutal review. This journey is interactive — the agent asks before every decision and never designs before the message is settled — and resumable, because every decision and artifact lives in the project's `docs/` folder. You drive the phases; the constituent skills carry the method. + +## Core Principle + +**Message before design, design before conversion — in that order; looks-fine is the floor, not the goal.** A visitor decides in five seconds whether to stay, and that decision rides on whether they instantly understand what you do and why it matters to *them* — so clarity comes first and design serves it. This skill sequences the phases, asks the questions, and records the decisions; the constituent skills carry the frameworks. Invoke them rather than improvising their method. + +## Journey Map + +| Phase | Skill | Question it answers | Artifact | +|---|---|---|---| +| 1 | one-page-marketing | Who is this for, and what is the site's one job? | Creates docs/MARKETING.md; extends docs/CUSTOMER.md | +| 2 | storybrand-messaging | What do we say, with the customer as hero? | Creates docs/POSITIONING.md, docs/WEBSITE.md | +| 3 | made-to-stick | How do we make the message memorable? | Extends docs/POSITIONING.md, docs/WEBSITE.md | +| 4 | top-design | What makes this page unforgettable to look at? | Creates docs/DESIGN.md | +| 5 | web-typography | Is the type readable as well as dramatic? | Extends docs/DESIGN.md | +| 6 | refactoring-ui | Is the design consistent and systematic? | Extends docs/DESIGN.md | +| 7 | ux-heuristics | Can anyone use it without thinking? | Extends docs/DESIGN.md | +| 8 | cro-methodology | Why don't visitors convert, and what answers them? | Extends docs/WEBSITE.md, docs/EXPERIMENTS.md | +| 9 | scorecard-marketing | How do we capture the not-ready-to-buy majority? | Extends docs/WEBSITE.md, docs/MARKETING.md | +| 10 | steve-jobs-design-review | Is it insanely great, or not done? | Extends docs/WEBSITE.md — GATE | + +## Operating Rules + +1. **Resume first.** Before anything else, read `docs/CREATE-WEBSITE-PLAN.md` and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted. +2. **Intake on first run only.** No tracker: run the Intake below, then create `docs/CREATE-WEBSITE-PLAN.md` with every phase statused `pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason`. Done when the tracker exists and the user has confirmed the phase plan. +3. **Phase entry.** Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase `in-progress` on proceed. Done when the user chose. +4. **Skill invocation and fallback.** Invoke the phase's skill by its slug. If it is not available, offer: `npx skills add wondelai/skills/ --global`. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in. +5. **In-phase decisions.** Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect. +6. **Phase exit.** Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows `done`. +7. **Artifact discipline.** Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in `docs/`. Every recommendation lands as a checkbox or a table row with owner and priority. See [references/artifact-templates.md](references/artifact-templates.md) when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names. +8. **Every scarcity claim, testimonial, and guarantee on the site must be true.** When a persuasion tactic needs inventing evidence, replace it with a tactic that uses evidence you have. + +## Intake + +Ask these before creating the tracker: + +1. What is the product or service, and who is it for? (Gates Phase 1's niche and avatar, and every word of the message.) +2. Do `docs/POSITIONING.md` or `docs/CUSTOMER.md` already exist from a create-business run? (If yes, lighten Phases 1-2 and reuse them; if positioning is thin, add the obviously-awesome optional phase.) +3. What is the single primary conversion goal — start a trial, book a demo, purchase, or take a quiz? (Gates every CTA decision in Phases 1, 8, 9.) +4. Full multi-page site or a single landing page? (Gates sitemap scope and whether Phases 8-9 apply.) +5. What is the tech stack and where does the code live? (So design and copy land in real files, not a hand-off doc.) +6. What proof assets exist today — testimonials, results, logos, guarantees? (Gates the Phase 8 persuasion audit and Rule 8.) +7. How much does craft matter — competing on design, or a functional site? (Gates whether Phases 4-5 run fully or lightly.) + +Skip heuristics: skip Phase 1 when a prior run already fixed the niche, avatar, and USP; run Phases 4-5 lightly for an internal or throwaway page where craft does not sell (never skip refactoring-ui); skip Phase 9 when one direct CTA suffices and there is no nurture motion; skip Phase 3 only under a brutal timeline — and warn that clear-but-forgettable copy evaporates. Then create the tracker from the template and confirm the plan. + +Done when `docs/CREATE-WEBSITE-PLAN.md` exists with every phase statused and the user has confirmed the plan. + +## Phases + +### Phase 1 — Frame the strategy and pick one niche (one-page-marketing) + +**Purpose:** Decide who the site is for, the USP, and the single primary conversion goal before any page exists. + +**Brief (fallback):** PVP Index — score candidate niches on Personal fulfillment, Value to the market, and Profitability, then pick *one*. "Speak to everyone, speak to no one." Write a USP that passes the swap test: if a competitor's name fits your tagline, it is too generic. Map the Before and During squares to concrete pages, each with one job. + +**Invoke:** `one-page-marketing` with the product and target from intake. Ask for (a) PVP scores for 2-3 niches, (b) a one-paragraph avatar, (c) a swap-test USP, (d) the Before/During squares mapped to homepage, landing, and lead-capture pages. + +**Decide with the user:** Which niche to dominate (recommend the highest PVP score)? What is the single primary conversion goal — trial, demo, purchase, or quiz lead? + +**Artifact:** Create docs/MARKETING.md with `## Target Market & Avatar` (niche, avatar, USP, primary goal) and `## Before / During / After Grid`. Extend docs/CUSTOMER.md with `## Segments & Best-Fit Customer`. Update the tracker. + +**Done when:** MARKETING.md names one niche, a swap-test USP, and one primary goal; CUSTOMER.md records the best-fit segment; the user confirmed the niche and goal. + +### Phase 2 — Write the message with StoryBrand (storybrand-messaging) + +**Purpose:** Write the words the visitor judges in five seconds — customer as hero, you as guide. + +**Brief (fallback):** SB7 — a Character who wants something, a Problem (external/internal/philosophical), a Guide with empathy and authority, a Plan, a call to Action, the stakes of Failure, a vivid Success. Name the internal problem (how it *feels*), not just the external one. One-liner: "We help [character] who struggle with [problem] to [solution] so they can [result]." + +**Invoke:** `storybrand-messaging` with the avatar and USP from MARKETING.md. Ask for a full BrandScript, homepage copy following the StoryBrand wireframe (header, stakes, value, guide, plan, CTA), and five one-liner variations ranked by repeatability. + +**Decide with the user:** Which one-liner is most repeatable after a single hearing? Confirm the customer, not the brand, is the hero — no opening "We…". + +**Artifact:** Create docs/POSITIONING.md with `## Brand Script (StoryBrand)`, `## One-Liner`, `## Key Messages`. Create docs/WEBSITE.md with `## Sitemap` and `## Page Briefs` (wireframe-derived copy blocks). Update the tracker. + +**Done when:** POSITIONING.md holds a complete BrandScript and a locked one-liner; WEBSITE.md has a sitemap and a homepage page brief; the user approved the one-liner. + +### Phase 3 — Make the message stick (made-to-stick) + +**Purpose:** Turn clear copy into memorable copy that survives the closed tab and gets repeated. + +**Brief (fallback):** SUCCESs — Simple, Unexpected, Concrete, Credible, Emotional, Story. Fight the Curse of Knowledge. Highest leverage is Concrete: replace every abstraction with a picture ("report generation from 4 hours to 10 minutes"). Add one unexpected hook, one Sinatra-test proof, and one named-customer story. + +**Invoke:** `made-to-stick` with the copy in WEBSITE.md `## Page Briefs` and the messages in POSITIONING.md. Ask for a SUCCESs score, concrete rewrites of every abstract benefit, one unexpected hero hook, and a short customer story. + +**Decide with the user:** Approve the sticky rewrites and pick the hero hook. Which numbers and claims are true and citable (this feeds Rule 8)? + +**Artifact:** Extend docs/POSITIONING.md `## Key Messages` (sticky versions) and docs/WEBSITE.md `## Page Briefs` (concrete copy). Update the tracker. + +**Done when:** every abstract benefit is a concrete outcome with a real, true number, one unexpected hook and one customer story exist, and the copy is signed off. + +### Phase 4 — Design the signature moment (top-design) + +**Purpose:** Make the page look agency-built, not template-built — starting from the one screenshot-worthy moment. + +**Brief (fallback):** Every pixel intentional. Start with the signature moment (usually the hero), not the header: dramatic scale (min 10:1 display-to-body), an asymmetric composition, a choreographed load with ~80ms staggered word reveals. Custom cubic-beziers (expo-out `0.16,1,0.3,1`), animate only `transform`/`opacity`, warm off-blacks (`#0a0a0a`) not pure black. Custom cursor only if the user opts in. + +**Invoke:** `top-design` with POSITIONING.md and the WEBSITE.md page briefs. Ask for the signature hero design, a custom color system (no AI purple-to-blue gradient), and a scored audit across typography, composition, motion, color, and details. + +**Decide with the user:** What is the signature moment worth screenshotting? Approve the color system. Custom cursor — yes, or native (recommend native unless craft is the product)? + +**Artifact:** Create docs/DESIGN.md with `## Design Direction` (signature moment, personality, references). Update the tracker. + +**Done when:** DESIGN.md names the signature moment and color system, the top-design audit scores are recorded, and the user approved the direction. + +### Phase 5 — Choose and tune the type (web-typography) + +**Purpose:** Make the type readable as well as dramatic — the discipline behind the drama. + +**Brief (fallback):** Clear-goblet principle — type serves content. "Type for a moment" (headlines) versus "type to live with" (body). Three measures beat typeface choice: 16-18px body, 45-75ch measure (66 optimal, `max-width: 65ch`), line height 1.5-1.7 body / 1.1-1.25 headings. One to two families. Under 200KB payload, WOFF2, variable fonts, `clamp()` fluid scale, preload + `font-display: swap`. + +**Invoke:** `web-typography` with DESIGN.md `## Design Direction`. Ask for a display+body pairing, full CSS (clamp scale, per-context line heights, 65ch measure), and a font-loading plan under 200KB with zero layout shift. + +**Decide with the user:** Approve the pairing; confirm the performance budget (recommend a single variable font to cut the file count). + +**Artifact:** Extend docs/DESIGN.md `## Typography` (typefaces, scale, measure, line height, loading strategy). Update the tracker. + +**Done when:** DESIGN.md `## Typography` specifies the pairing, scale, measures, and a sub-200KB loading strategy, and the user approved the pairing. + +### Phase 6 — Make it systematic (refactoring-ui) + +**Purpose:** Add the consistency that keeps the wow from collapsing on the second and third sections. + +**Brief (fallback):** Design in grayscale first, add color last. Systems over talent: constrained scales for spacing (4, 8, 16, 24, 32, 48, 64), type, color, and shadow. Hierarchy from combining levers (large OR bold OR dark), saving all three for one element. Space between groups exceeds space within. Near-black (`#111827`) not pure `#000`, tinted grays. Two-layer shadows mapped to elevation. Run the blur test. + +**Invoke:** `refactoring-ui` with DESIGN.md. Ask for a grayscale hierarchy audit, a constrained token set (spacing, a 9-shade palette with tinted grays, a type scale, a shadow scale), and refactored button/form/card components with one primary action per section. + +**Decide with the user:** Approve the token scales; confirm the primary/secondary/tertiary button hierarchy. + +**Artifact:** Extend docs/DESIGN.md `## Tokens` (spacing, palette, shadows) and `## Components` (per-component decisions). Update the tracker. + +**Done when:** DESIGN.md defines the token scales and component decisions, buttons show one clear primary per section, and the user approved the tokens. + +### Phase 7 — Make it effortless to use (ux-heuristics) + +**Purpose:** Remove the friction of making a visitor think. + +**Brief (fallback):** Pages must be self-evident; users scan, satisfice, and muddle through. Trunk Test — dropped onto any page cold, can they answer what site, what page, what sections, and where to go next? Run "get rid of half the words." Plain-language CTAs. Inline validation on blur, mark optional not required fields, 44x44px tap targets, visible system status ("Saving…"/"Saved", skeletons, confirmations). + +**Invoke:** `ux-heuristics` with WEBSITE.md and DESIGN.md. Ask for a usability audit against Krug's laws and Nielsen's 10 heuristics, each issue rated 0-4, plus rewritten error messages and CTA labels. + +**Decide with the user:** Approve the prioritized fix list starting with catastrophic (4) issues; confirm which fixes ship before launch versus later. + +**Artifact:** Extend docs/DESIGN.md `## UX Audit Findings` (Issue | Heuristic | Severity | Fix | Status). Update the tracker. + +**Done when:** every page passes the Trunk Test, catastrophic issues are fixed, UX Audit Findings are logged with severities, and the user approved the fix order. + +### Phase 8 — Engineer the conversion (cro-methodology) + +**Purpose:** Turn a clear, usable page into one that answers the real reasons visitors don't convert. + +**Brief (fallback):** Don't guess — discover. Build an Objection/Counter table for the Big 5 (Trust, Price, Fit, Timing, Effort); place each counter at the point of friction, never buried in an FAQ; use "CO Only" for objections a visitor won't admit. Proof hierarchy: specific results with context > named testimonials > case studies > bare logos. Proof sandwich; specific numbers ("47,832" not "about 50,000"). + +**Invoke:** `cro-methodology` with WEBSITE.md and the proof assets from intake. Ask for a Big-5 Objection/Counter table with placements, a persuasion-asset audit ranked by the proof hierarchy, a wish list of missing proof, and A/B test hypotheses. + +**Decide with the user:** Which counters ship now versus await proof you must acquire? Confirm no counter invents evidence (Rule 8). + +**Artifact:** Extend docs/WEBSITE.md `## Conversion Elements` (Objection | Counter | Placement | Status). Extend docs/EXPERIMENTS.md `## Experiment Cards` and `## Experiment Backlog`. Update the tracker. + +**Done when:** the Big-5 table has an evidence-backed counter and placement per objection, missing proof is listed as actions, test hypotheses are logged, and no counter relies on invented evidence. + +### Phase 9 — Add a lead-generating quiz (scorecard-marketing) + +**Purpose:** Capture the ~97% not ready to buy today with a lower-commitment offer. + +**Brief (fallback):** Everything is downstream from lead generation; a quiz converts 30-50% versus 3-10% for a static PDF. Four steps: a landing page (concept hook + the 3 Cs — Clarity, Credibility, Connection), a questionnaire that captures the email *before* the questions, a tiered results page, and a segmented follow-up. "Moving toward" hooks beat fear-based ones. Keep it to 8-15 questions for cold traffic. + +**Invoke:** `scorecard-marketing` with the primary goal and avatar. Ask for a concept hook and landing page, 10-12 scored questions in 3-4 categories, three result tiers with dynamic copy and a CTA each, and a follow-up sequence segmented by tier. + +**Decide with the user:** Does the site need a lead-nurture motion? If one direct CTA suffices, skip this phase. Otherwise approve the concept hook. + +**Artifact:** Extend docs/WEBSITE.md `## Lead Capture` (quiz funnel design). Extend docs/MARKETING.md `## Nurture Sequences` (tiered follow-up). Update the tracker. + +**Done when:** WEBSITE.md `## Lead Capture` specifies a hook, ≤15 questions with email captured first, and tiered results; MARKETING.md holds the segmented follow-up; the hook promises only what the assessment delivers. + +### Phase 10 — Hold it to an insanely-great bar (steve-jobs-design-review) — GATE + +**Purpose:** Subject the finished site to one brutal, honest review before a single visitor sees it. + +**Brief (fallback):** "Start with the customer experience and work backwards." Experience it cold as a stranger. State the One Thing in a single sentence. Count steps-to-value (three, not nine). Walk the slow paths — empty form, error state, failed payment, mobile cold-start. Check the back of the fence — 404, error copy, confirmation email. The verdict is binary: insanely great, or not done. Focusing is saying no. + +**Invoke:** `steve-jobs-design-review` with the live site or full page set. Ask for a cold first impression, the One Thing, a steps-to-value count, a walk of the failure/empty states and the back of the fence, a binary verdict, and a ranked cut list plus fix list. + +**Decide with the user:** Act on the cut list — what to delete to protect the single primary goal? If the verdict is NOT DONE, which fixes are blocking launch? + +**Artifact:** Extend docs/WEBSITE.md `## Audit Findings` (Issue | Severity | Fix | Status) with the cut list and fix list. Update the tracker. + +**Done when:** the verdict is INSANELY GREAT (not "pretty good"), the cut list is applied, the back of the fence is checked, and blocking fixes are closed — only then does the site launch. + +## Optional Phases + +| Skill | Add when | Artifact | +|---|---|---| +| obviously-awesome | `docs/POSITIONING.md` does not exist yet and the messaging has nothing to stand on | Creates docs/POSITIONING.md | +| influence-psychology | Pricing or signup pages need persuasion-principle audits | Extends docs/WEBSITE.md | +| high-perf-browser | Core Web Vitals or load speed threaten conversions | Extends docs/WEBSITE.md | +| design-everyday-things | Forms or flows confuse users despite clean visuals | Extends docs/DESIGN.md | +| microinteractions | The site needs interaction polish beyond static design | Extends docs/DESIGN.md | + +Optional phases follow the same operating rules; insert where the Add-when condition first becomes true. + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Designing before you have a message | Run Phase 2 (storybrand) and Phase 3 before Phase 4 (top-design); design serves the words, never the reverse. | +| Making your brand the hero | In storybrand, open with the customer's problem and desired outcome; if the first sentence starts with "We," rewrite it. | +| Stacking competing calls to action | Keep one direct CTA and one transitional; refactoring-ui and the Jobs review both enforce one primary action per section. | +| Confusing clear with sticky | Run the made-to-stick pass — concrete numbers, one unexpected hook, one customer story — so the message survives the closed tab. | +| Testing button colors instead of objections | Build the Objection/Counter table in cro-methodology first; "meek tweaks" rarely move conversion. | +| Polished happy path, broken everywhere else | In the Jobs review, walk the empty state, form error, 404, confirmation email, and mobile cold-start — the back of the fence. | + +## Completing the Journey + +Exit checklist: +- [ ] POSITIONING.md holds a BrandScript, a repeatable one-liner, and key messages consistent across surfaces +- [ ] WEBSITE.md has a sitemap, page briefs with copy, an Objection/Counter table, and (if in scope) a lead-capture design +- [ ] DESIGN.md defines direction, typography, tokens, components, and a passed UX audit +- [ ] The Steve Jobs review returned INSANELY GREAT — not "pretty good" — and the cut list is applied +- [ ] Every scarcity claim, testimonial, and guarantee on the page is true + +Close the tracker: every phase `done` or `skipped: reason`, with any remaining Next Actions carried into the artifacts as checkboxes. Then route forward: when the site is live and conversion data starts arriving, continue with `improve-website` to turn today's assumptions into tested wins. When the website sells a product that now needs building, continue with `create-app`. diff --git a/.agents/skills/create-website/references/artifact-templates.md b/.agents/skills/create-website/references/artifact-templates.md new file mode 100644 index 00000000..0682466d --- /dev/null +++ b/.agents/skills/create-website/references/artifact-templates.md @@ -0,0 +1,149 @@ +# Artifact Templates — create-website + +Skeletons this metaskill creates in the user's docs/ folder. Extend-only artifacts (CUSTOMER.md, EXPERIMENTS.md) are governed by the section headings named in each phase — read them before writing and preserve everyone else's sections. + +## docs/CREATE-WEBSITE-PLAN.md (tracker) + +```markdown +# Create Website Plan + +## Context +Intake answers, date started, project specifics. + +## Phase Status +| Phase | Skill | Status | Artifact | Date | +|---|---|---|---|---| +| 1 | one-page-marketing | pending | MARKETING.md, CUSTOMER.md | | +| 2 | storybrand-messaging | pending | POSITIONING.md, WEBSITE.md | | +| 3 | made-to-stick | pending | POSITIONING.md, WEBSITE.md | | +| 4 | top-design | pending | DESIGN.md | | +| 5 | web-typography | pending | DESIGN.md | | +| 6 | refactoring-ui | pending | DESIGN.md | | +| 7 | ux-heuristics | pending | DESIGN.md | | +| 8 | cro-methodology | pending | WEBSITE.md, EXPERIMENTS.md | | +| 9 | scorecard-marketing | pending | WEBSITE.md, MARKETING.md | | +| 10 | steve-jobs-design-review | pending | WEBSITE.md | | +Statuses: pending · in-progress · awaiting-evidence · done · deferred: · skipped: + +## Key Decisions +| Date | Phase | Decision | Rationale | +|---|---|---|---| + +## Next Actions +- [ ] action (owner, due) +``` + +## docs/MARKETING.md + +Created in Phase 1; `## Nurture Sequences` extended in Phase 9. + +```markdown +# Marketing + +## Target Market & Avatar +PVP niche choice · one-paragraph avatar. + +## Before / During / After Grid +| Phase | Square | Current state | Plan | +|---|---|---|---| + +## Channels +| Channel | Approach | Owner | Status | +|---|---|---|---| + +## Word-of-Mouth (STEPPS) +| Lever | Idea | Status | +|---|---|---| + +## Outbound Process +Roles, sequences, qualification, handoff. + +## Referral & Invite Mechanics + +## Nurture Sequences +``` + +## docs/POSITIONING.md + +Created in Phase 2 (Brand Script, One-Liner, Key Messages). If the optional obviously-awesome phase runs first, it creates the file with the canvas sections above the messaging ones. + +```markdown +# Positioning & Messaging + +## Competitive Alternatives + +## Unique Attributes → Value Themes +| Attribute | Value ("so what") | Proof | +|---|---|---| + +## Best-Fit Customer + +## Market Category +Choice (existing / subcategory / new) and rationale. + +## One-Liner + +## Brand Script (StoryBrand) +Character · Problem (external/internal/philosophical) · Guide · Plan · Call to action · Failure · Success. + +## Key Messages +| Surface | Message | Status | +|---|---|---| +``` + +## docs/WEBSITE.md + +Created in Phase 2 (Sitemap, Page Briefs); Conversion Elements added in Phase 8, Lead Capture in Phase 9, Audit Findings in Phases 7 and 10. + +```markdown +# Website + +## Sitemap + +## Page Briefs +### / (home) +- Purpose & primary conversion action: +- Message (from POSITIONING.md): +- CTA (direct + transitional): +- Copy blocks: + +## Conversion Elements +| Objection (Big 5) | Counter | Placement | Status | +|---|---|---|---| + +## Audit Findings +| Issue | Severity (0-4) | Fix | Status | +|---|---|---|---| + +## Lead Capture +Scorecard/quiz funnel design. +``` + +## docs/DESIGN.md + +Created in Phase 4 (Design Direction); Typography added in Phase 5, Tokens + Components in Phase 6, UX Audit Findings in Phase 7. + +```markdown +# Design System + +## Design Direction +Signature moment, personality, references. + +## Typography +Typefaces, scale, measure, line height, loading strategy. + +## Tokens +Spacing scale · color palette (shades, tinted grays) · shadows. + +## Components +| Component | Decision | Status | +|---|---|---| + +## UX Audit Findings +| Issue | Heuristic | Severity (0-4) | Fix | Status | +|---|---|---|---|---| + +## Microinteraction Inventory +| Interaction | Trigger/Rules/Feedback/Loops | Fix | Status | +|---|---|---|---| +``` diff --git a/.agents/skills/cro-methodology/SKILL.md b/.agents/skills/cro-methodology/SKILL.md new file mode 100644 index 00000000..cb780af4 --- /dev/null +++ b/.agents/skills/cro-methodology/SKILL.md @@ -0,0 +1,227 @@ +--- +name: cro-methodology +description: 'Audit websites and landing pages for conversion issues and design evidence-based A/B tests. Use when the user mentions "landing page isnt converting", "conversion rate", "A/B test", "why visitors leave", "objection handling", "bounce rate", "conversion funnel", "increase signups", or "people add to cart but dont buy". Also trigger when diagnosing why signups are low, designing experiment hypotheses, or auditing checkout flows for friction points. Covers funnel mapping, persuasion assets, and objection/counter-objection frameworks. For overall marketing strategy, see one-page-marketing. For usability issues, see ux-heuristics.' +license: MIT +metadata: + author: wondelai + version: "1.5.0" +--- + +# CRO Methodology + +Scientific, customer-centric approach to conversion rate optimization based on the CRE Methodology(TM). Extraordinary improvements come from understanding WHY visitors don't convert, not from copying competitors or applying generic tips. + +## Core Principle + +**Don't guess -- discover.** Every visitor who doesn't convert has a reason. Discover those reasons through research, then systematically eliminate them with evidence and proof. This evidence-based approach consistently outperforms "best practices", intuition, competitor copying, and expert opinion. + +## Scoring + +**Goal: 10/10.** Score any landing page, funnel, or conversion flow against the seven Quick Diagnostic rows below: award ~1.4 points per row answered "yes" (7 rows = 9.8, capped at 10). Bands: **9-10** = single clear action, research-grounded O/CO table, value prop legible in 5 seconds, proof at every friction point, funnel mapped, path free of UX blockers; **5-6** = guessed objections, generic best-practices copy, proof buried in FAQs; **<=3** = competing CTAs, no funnel map, claims with no proof. Report the current score and the specific diagnostic rows failing. + +## The CRO Frameworks + +### 1. The CRO Process + +**Core concept:** A systematic 9-step process moving from defining success metrics through research and experimentation to scaling wins across the business. + +**Why it works:** Random optimization skips research. The process forces you to understand visitors before changing anything, so every change rests on evidence, not opinion. + +**Key insights:** +- Define success metrics aligned with business KPIs before touching any page +- Map the entire funnel to find "blocked arteries" (high-traffic underperforming paths) and "missing links" (absent funnel stages) +- Research visitors in three dimensions: who they are, what blocks them (UX problems), what stops them (objections) +- Gather market intelligence from competitors, reviews, and other industries +- Prioritize ideas with ICE scoring; design bold experiments, not "meek tweaks" +- Run experiments with statistical rigor (95% confidence minimum, full business cycles), then scale wins across the business + +**Product applications:** + +| Context | CRO Process Step | Example | +|---------|-----------------|---------| +| **Landing page audit** | Define goals, map funnel, research visitors | 70% bounce because value prop is unclear | +| **Checkout optimization** | Map funnel for blocked arteries | Shipping cost shock causes 40% cart abandonment | +| **Email sequence** | Scale wins | Winning objection-handling copy reused in drip emails | + +**Copy patterns:** +- "What's preventing you from [action] today?" (exit survey to discover objections) +- "Here's what [X] customers found..." (counter-objection with social proof) + +See [funnel-analysis.md](references/funnel-analysis.md) when mapping the funnel -- step-by-step mapping, blocked-artery/missing-link diagnosis, industry funnel benchmarks, and impact-based prioritization. + +### 2. Customer Research & Objections + +**Core concept:** Visitors fail to convert for specific, discoverable reasons. Exit surveys, chat logs, support tickets, sales calls, and reviews reveal the "voice of the customer" and their real objections. + +**Why it works:** Teams' guesses about why visitors leave are almost always wrong. Research uncovers objections no one anticipated, and the customer's own language out-persuades any copywriter's invention. + +**Key insights:** +- Primary sources (exit surveys, live chat, tickets, sales calls) give direct visitor language; secondary sources (reviews, social media, competitors) reveal industry-wide objections +- The "Big 5" universal objections: Trust, Price, Fit, Timing, Effort +- Quantitative research (analytics, heatmaps) shows WHERE problems are; qualitative (surveys, interviews) shows WHY +- Non-converter surveys should ask ONE question for maximum response; post-purchase surveys ("What almost stopped you from buying?") reveal the objections that matter most + +**Product applications:** + +| Context | Research Method | Example | +|---------|---------------|---------| +| **Exit intent** | On-site survey | "What's preventing you from signing up today?" | +| **Post-purchase** | Email survey within 7 days | "What almost stopped you from buying?" | +| **Objection mining** | Support tickets + reviews | Search "but", "however", "worried about"; negative reviews = unaddressed objections | + +**Copy patterns:** +- Use exact customer language in headlines and body copy -- it outperforms polished marketing copy +- "What's the one thing we could change to make you [action]?" +- "How would you describe [product] to a friend?" (reveals positioning in customer terms) + +**Ethical boundary:** Anonymize data, get consent for recordings, and don't survey so aggressively that you degrade the experience. + +See [RESEARCH.md](references/RESEARCH.md) when planning research -- ready-to-use survey questions per channel, recommended tools, and how to turn raw responses into a ranked objection list. + +### 3. Persuasion Assets + +**Core concept:** Every company sits on overlooked proof -- undisplayed testimonials, unmentioned awards, hidden credentials, buried guarantees. Inventory these "persuasion assets", acquire missing ones, display them. + +**Why it works:** Visitors decide on evidence, not claims. A modest claim with overwhelming proof beats a bold claim with none. + +**Key insights:** +- Audit five categories: Credentials & Authority, Social Proof, Risk Reversal, Data & Specificity, Process & Methodology +- Create a wish list for missing assets and actively acquire them (request testimonials, apply for awards, compile statistics) +- "Proof sandwich" structure: Claim (bold promise), then Proof (evidence), then Reinforcement (secondary proof) +- Proof hierarchy, strongest first: specific results with context > named testimonials with photos > case studies > statistics > logos > generic testimonials +- Place proof at points of friction, not in FAQs; specific numbers beat round ones ("47,832 customers" beats "About 50,000") + +**Product applications:** + +| Context | Persuasion Asset | Example | +|---------|-----------------|---------| +| **Landing page header** | Logo bar + rating | "Trusted by 10,000+ companies" with 5 recognizable logos | +| **Pricing page** | Risk reversal | "30-day money-back guarantee, no questions asked" | +| **Checkout flow** | Trust badges near forms | Security certification, payment logos, guarantee seal | + +**Copy patterns:** +- "Here's how we did it for [Company X]..." (case study proof) +- "[Specific number] businesses trust us" (not "thousands of customers") +- Lead with benefits, not features: "Never delete another photo" beats "256GB storage" + +**Ethical boundary:** Never fabricate testimonials, inflate statistics, or display fake trust badges -- all proof must be genuine and verifiable. + +See [PERSUASION.md](references/PERSUASION.md) when auditing or acquiring proof -- the full five-category asset checklist and psychological triggers. See [COPYWRITING.md](references/COPYWRITING.md) when writing the proof copy itself -- headline formulas, benefit-led phrasing, and proof-element wording. + +### 4. The O/CO Framework + +**Core concept:** The Objection/Counter-Objection table is the core CRE technique: map every visitor objection to a specific, evidence-backed counter-objection. + +**Why it works:** The table forces every counter to be placed where its objection arises in the reading flow, so a concern is answered the instant the visitor feels it -- not pages later, by which point they have already left. + +**Key insights:** +- Research objections from surveys, chat logs, tickets, and sales calls -- don't guess +- Implicit objections (ones visitors won't admit) require "CO Only": counter without stating the objection +- Place counter-objections at the point of friction (credit-card objection near the payment form), not buried in FAQ +- Address primary objections above the fold; repeat the same counter in multiple formats (text, video, testimonial, data) +- Canned support responses are goldmines of tested counter-objections + +**Product applications:** + +| Objection | Visitor Question | Counter-Objections | +|-----------|------------------|--------------------| +| **Trust** | "Why should I believe you?" | Named testimonials, media logos, awards, guarantee | +| **Price** | "Is it worth the money?" | ROI calculator, cost comparison vs. alternatives, payment plans | +| **Fit** | "Will it work for MY situation?" | Similar-customer case studies, segmented pages, free trial | +| **Timing** | "Why act now?" | Cost-of-delay math, genuine limited offers, seasonal relevance | +| **Effort** | "How hard will this be?" | "Done for you" framing, "Set up in 5 minutes", step-by-step breakdown | + +**Copy patterns:** +- Bad (states implicit objection): "Worried you're too lazy to learn a language?" +- Good (CO Only): "Let the audio do the work for you." +- "What almost stopped you from buying?" (post-purchase survey to validate the O/CO table) + +**Ethical boundary:** A counter-objection must resolve the concern with real evidence, not dismiss a legitimate worry as unfounded. + +See [OBJECTIONS.md](references/OBJECTIONS.md) when building the O/CO table -- per-category counter-objection technique catalogs, CO-Only patterns for implicit objections, and how to mine objections from support logs. + +### 5. Hypothesis Design + +**Core concept:** Every experiment needs a documented hypothesis linking a specific change to an expected outcome for a research-grounded reason, prioritized with ICE scoring (Impact, Confidence, Ease). + +**Why it works:** A hypothesis forces you to articulate WHY a change should work, grounding it in customer research. ICE scoring stops teams wasting traffic on low-impact tweaks. + +**Key insights:** +- Format: "If we [change X], then [metric Y] will improve because [reason based on research]" +- Define primary (decides winner), secondary (monitoring), and guardrail (must not decrease) metrics before testing +- ICE, 1-10 each: Impact (could this double conversion?), Confidence (how strong is the research?), Ease (how easy to implement?); prioritize by the average +- The 10x screen: if a change couldn't 10x results, deprioritize it. Worth testing: complete redesign, new value proposition, fundamentally different offer. Not worth testing: button color, font size, image swap + +**Worked example:** "Customer language from surveys will lift signups because visitors see their own words" scores I:8, C:9, E:10 = 9.0 -- a top-priority test. A button-color swap scores ~I:2, C:2, E:10 = 4.7 and gets skipped despite being trivial to build. + +**Copy patterns:** +- "Based on our research, visitors' #1 objection is [X]. This test addresses it by [Y]." +- Document before: hypothesis, primary metric, sample size, duration. Document after: raw numbers, confidence interval, learnings, next steps + +See [testing-methodology.md](references/testing-methodology.md) when prioritizing or scoring a backlog -- per-axis ICE scoring rubrics, a worked prioritization table, and the weighted-ICE variant. + +### 6. A/B Testing Methodology + +**Core concept:** Run controlled experiments comparing page versions with proper statistical rigor, so results reflect reality rather than random noise. + +**Why it works:** Without rigor you can't distinguish real improvements from random variation -- peeking, undersized samples, and ignored practical significance all manufacture false winners. + +**Key insights:** +- Calculate required sample size BEFORE starting (baseline rate, minimum detectable effect, 80% power, 95% significance) +- Run at least one full business cycle (1-2 weeks), covering weekdays AND weekends +- Never peek at results and stop early -- it dramatically inflates false positives +- Practical significance matters: a statistically significant 0.1% lift isn't worth implementation complexity +- Use multivariate only with 100k+ monthly visitors on a proven winning page +- Promote winners to the new control; a failed test that teaches you something beats a win you don't understand + +**Product applications:** + +| Context | Test Type | Example | +|---------|----------|---------| +| **Concept validation** | A/B test (2-4 variants) | Two fundamentally different layouts based on different customer insights | +| **Low traffic** | Bold A/B test | Dramatic changes reach significance on far smaller samples than timid ones | +| **Post-test** | Scale wins | Apply winning insights to landing pages, ad copy, email sequences | + +**Copy patterns:** +- "We increased [metric] by [X]% with [Y]% confidence over [Z] weeks" +- "Test showed no significant difference, teaching us that [insight about customers]" +- Document learnings: Test, Hypothesis, Result, Learning, Applicable to + +**Reporting rule:** Decide sample size and duration up front, then report whatever the pre-set test returns -- never stop early on a peeked "winner," rerun a test until it yields the answer you want, or bury an inconclusive result. (This is the one honest-reporting constraint for the whole methodology.) + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|------| +| **Copying competitors blindly** | You don't know if it even works for them | Research YOUR visitors' objections, build YOUR evidence | +| **Testing button colors before understanding objections** | Surface symptoms, tiny effects, wasted sample | Customer research first, then test big changes | +| **Assuming you know why visitors leave** | Teams are almost always wrong about motivations | Exit surveys, chat logs, support-ticket analysis | +| **Applying "best practices" unvalidated** | May not fit your audience, product, or context | Treat them as hypotheses to test, not rules | +| **HiPPO decisions** | Highest Paid Person's Opinion is not data | Let research and test results decide, not seniority | +| **Optimizing pages without funnel context** | Fixes shift problems elsewhere; misses biggest wins | Map the funnel, find blocked arteries, prioritize by impact | +| **Meek tweaks instead of bold changes** | Rarely reach significance; waste time and traffic | Test changes that could double conversion, not nudge it 2% | +| **Giving up after one failed test** | The opportunity still exists | Investigate why, return to research, try a bolder change | + +## Quick Diagnostic + +Audit any landing page or conversion flow: + +| Question | If No | Action | +|----------|-------|--------| +| Do we know the ONE action visitors should take? | Page lacks focus | Define a single conversion goal; remove competing CTAs | +| Have we researched (not guessed) why visitors don't convert? | Optimization built on assumptions | Run exit surveys, analyze chat logs and tickets | +| Do we have an O/CO table? | Objections go unanswered | Build it from research; place counters at friction points | +| Is the value proposition clear within 5 seconds? | Visitors bounce before understanding | Run a 5-second test; rewrite headline in customer language | +| Are persuasion assets visible (testimonials, awards, guarantees)? | Claims without proof aren't believed | Audit assets, acquire missing ones, display prominently | +| Have we mapped the funnel for blocked arteries? | Optimizing the wrong page | Map traffic per stage, compare to benchmarks, prioritize | +| Is the path free of UX blockers (speed, mobile, form length)? | Friction kills converts who already decided to act | Fix load time, mobile layout, and over-long forms first | + +## Further Reading + +For the complete CRE Methodology(TM), detailed case studies, and advanced techniques: + +- [*"Making Websites Win: Apply the Customer-Centric Methodology That Has Doubled the Sales of Many Leading Websites"*](https://www.amazon.com/Making-Websites-Win-Customer-Centric-Methodology/dp/1544500513?tag=wondelai00-20) by Dr. Karl Blanks and Ben Jesson + +## About the Author + +**Dr. Karl Blanks and Ben Jesson** are cofounders of Conversion Rate Experts, the agency whose CRE Methodology has doubled the sales of many leading websites -- clients include Google, Apple, Amazon, Facebook, and Dropbox -- and earned a Queen's Award for Enterprise (Innovation). Blanks holds a PhD and led usability teams at Hewlett-Packard; Jesson's background is direct-response marketing. Their book *Making Websites Win* distills the methodology into a repeatable, evidence-based process. diff --git a/.agents/skills/cro-methodology/references/COPYWRITING.md b/.agents/skills/cro-methodology/references/COPYWRITING.md new file mode 100644 index 00000000..397c281c --- /dev/null +++ b/.agents/skills/cro-methodology/references/COPYWRITING.md @@ -0,0 +1,178 @@ +# Persuasive Copywriting for CRO + +Evidence-based copywriting principles. Write as much as it takes to communicate your entire sales message—but not one word more. + +## Headlines + +The headline's job: Get visitors to read the next line. + +### Headline Formulas That Work + +**Problem-agitate-solve**: +"Tired of [problem]? [Solution] lets you [benefit]." + +**Specificity wins**: +Bad: "Improve your conversion rate" +Good: "How we increased conversions by 363%" + +**News angle**: +"[X] facts about [topic] you were never told" + +**How-to**: +"How to [achieve result] without [common pain]" + +**Question**: +"What's stopping your website from converting?" + +### Headline Testing Priority + +1. Value proposition clarity +2. Specific numbers/results +3. Audience targeting +4. Urgency/timeliness +5. Emotional hook + +## Body Copy Principles + +### Length +Write as much as it takes to: +- Communicate the complete sales message +- Address all major objections +- Provide sufficient proof + +Long copy works when visitors are: +- Unfamiliar with product category +- Making a high-commitment decision +- Comparing alternatives + +Short copy works when: +- Brand is well-known +- Product is simple/commoditized +- Visitors are already convinced + +### Structure + +**Lead with benefits, not features** +Feature: "256GB storage" +Benefit: "Never delete another photo" + +**Use specific numbers** +Weak: "Thousands of customers" +Strong: "47,832 businesses trust us" + +**Write for scanners** +- Subheadings that tell the story alone +- Bold key phrases +- Bullet points for multiple items +- Short paragraphs (2-4 sentences) + +### Voice + +**Clarity over cleverness** +No reader is too sophisticated for simple sentences. + +**Active voice** +Bad: "Your conversion rate will be improved" +Good: "We'll improve your conversion rate" + +**"You" focus** +Count "you" vs. "we" in your copy. Visitors care about themselves. + +**Circle adjectives and adverbs** +Replace vague modifiers with specific facts: +Bad: "incredibly fast delivery" +Good: "delivery in 2 hours or less" + +## Proof Elements + +### Hierarchy of proof (strongest to weakest) + +1. **Specific results with context** + "Increased revenue by $2.4M in 6 months" + +2. **Named testimonials with photos** + Real people, real companies, specific outcomes + +3. **Case studies** + Problem → Solution → Results format + +4. **Statistics and data** + Industry benchmarks, research findings + +5. **Logos and badges** + Client logos, media mentions, certifications + +6. **Generic testimonials** + Unnamed quotes (weakest form) + +### Testimonial Best Practices + +**Include specifics**: +Bad: "Great product!" +Good: "Increased our conversion rate from 2.1% to 4.7% in 3 weeks" + +**Address objections**: +Choose testimonials that counter specific fears + +**Match the audience**: +B2B visitors want testimonials from similar companies/roles + +**Use photos**: +Real photos > stock photos > no photos + +## Calls-to-Action + +### CTA Copy + +**Benefit-oriented**: +Bad: "Submit" +Good: "Get my free report" + +**Reduce perceived commitment**: +"Start free trial" vs. "Sign up" +"See pricing" vs. "Buy now" + +**Match button to promise**: +If page promises "10 ways to improve X", CTA should be: +"Show me the 10 ways" not "Learn more" + +### CTA Placement + +- Above the fold (for aware visitors) +- After each major section +- At moment of peak interest +- Sticky/floating for long pages + +### CTA Testing Ideas + +1. Benefit vs. action language +2. Commitment level (free vs. buy) +3. Urgency elements +4. Size and color (test AFTER copy) +5. Number of CTAs per page + +## Common Copywriting Mistakes + +1. **Features without benefits** + Always answer "So what?" + +2. **Vague claims** + "Best in class" → "Rated #1 by [source]" + +3. **Talking about yourself** + Reframe everything around the visitor + +4. **Burying the lead** + Put most important information first + +5. **Assuming knowledge** + Explain industry jargon + +6. **Missing objections** + Address hesitations head-on + +7. **Weak proof** + Generic testimonials, no specifics + +8. **Unclear next step** + Always make the action obvious diff --git a/.agents/skills/cro-methodology/references/OBJECTIONS.md b/.agents/skills/cro-methodology/references/OBJECTIONS.md new file mode 100644 index 00000000..c7bea9f9 --- /dev/null +++ b/.agents/skills/cro-methodology/references/OBJECTIONS.md @@ -0,0 +1,135 @@ +# Objection/Counter-Objection (O/CO) Framework + +The core CRE technique for increasing conversions. Don't guess objections—research them. Then systematically counter each one. + +## The O/CO Table + +Create a two-column table: + +| Objection | Counter-Objection | +|-----------|-------------------| +| "It's too expensive" | ROI calculator, payment plans, comparison with alternatives | +| "I don't trust this company" | Testimonials, awards, media mentions, guarantees | +| "It won't work for my situation" | Case studies from similar customers, free trial | + +## How to Discover Objections + +### Primary Sources (Direct from visitors) + +**Exit surveys** (Qualaroo, Hotjar, etc.) +- "What's preventing you from signing up today?" +- "What questions do you still have?" +- "What would make this decision easier?" + +**Live chat logs** +- Search for patterns in "but", "however", "worried about" +- Note recurring hesitations + +**Support tickets** +- Pre-purchase questions reveal objections +- "Canned responses" are goldmines of tested counter-objections + +**Sales call recordings** +- What objections do salespeople hear repeatedly? +- What counter-arguments work? + +**"Refer a friend" messages** +- How do customers describe you to friends? +- What do they emphasize? What do they downplay? + +### Secondary Sources + +**Reviews (yours and competitors')** +- Negative reviews = unaddressed objections +- Positive reviews = effective counter-objections + +**Social media mentions** +- Reddit, Twitter threads about your category +- Forums where your audience discusses alternatives + +**Competitor analysis** +- What objections do competitors address? +- What proof do they emphasize? + +## Types of Objections + +### Explicit objections +Easy to address—visitors state them clearly: +- "Too expensive" +- "No free trial" +- "Requires credit card" + +### Implicit objections +Harder to identify—visitors won't admit them: +- "I'm lazy and don't want to do the work" +- "I'm not sure I'll follow through" +- "This seems too good to be true" + +**Technique for implicit objections**: Use "CO Only" approach—address the objection without stating it. + +Bad: "Worried you're too lazy to learn a language?" +Good: "Let the audio do the work for you." + +### The "Big 5" Universal Objections + +Most products face some version of: + +1. **Trust**: "Why should I believe you?" +2. **Price**: "Is it worth the money?" +3. **Fit**: "Will it work for MY situation?" +4. **Timing**: "Why should I act now?" +5. **Effort**: "How hard will this be?" + +## Counter-Objection Techniques + +### For Trust objections +- Specific testimonials (with photos, names, results) +- Media logos ("As seen in...") +- Awards and certifications +- Team credentials +- Years in business, customers served +- Money-back guarantee + +### For Price objections +- ROI calculators +- Cost comparison (vs. alternatives, vs. not solving problem) +- Payment plans +- Price anchoring (show higher-priced option first) +- Emphasize value, not features + +### For Fit objections +- Case studies from similar situations +- Segmented landing pages +- "Perfect for [specific audience]" messaging +- FAQ addressing edge cases +- Free trial or sample + +### For Timing objections +- Limited-time offers (genuine scarcity only) +- Cost of delay +- Seasonal relevance +- Urgency-building statistics + +### For Effort objections +- "Done for you" framing +- Step-by-step breakdown +- Time estimates ("Set up in 5 minutes") +- Onboarding support +- "System" or "process" language + +## Placement Strategy + +Don't hide objections in FAQ. Address them: + +- **At point of friction**: Credit card objection → right below payment form +- **In the flow**: As objections naturally arise during reading +- **Above the fold**: For primary objections +- **Multiple times**: Different formats (text, video, testimonial) + +## O/CO Audit Questions + +1. What are our visitors' top 5 objections? +2. Which are we NOT addressing on the page? +3. Which are we addressing weakly (no proof)? +4. Are counter-objections placed where objections arise? +5. What counter-objections do competitors use that we don't? diff --git a/.agents/skills/cro-methodology/references/PERSUASION.md b/.agents/skills/cro-methodology/references/PERSUASION.md new file mode 100644 index 00000000..d5b9859f --- /dev/null +++ b/.agents/skills/cro-methodology/references/PERSUASION.md @@ -0,0 +1,158 @@ +# Persuasion Assets & Psychological Triggers + +Your website should be a "proof magnet." Identify, acquire, and display persuasive assets. + +## Persuasion Assets Audit + +### Credentials & Authority +- [ ] Industry awards +- [ ] Certifications +- [ ] Media mentions (logo bar) +- [ ] Speaking engagements +- [ ] Published books/research +- [ ] Years in business +- [ ] Number of customers/users +- [ ] Team credentials/bios +- [ ] Patents or proprietary technology + +### Social Proof +- [ ] Customer testimonials (with photos, names, results) +- [ ] Video testimonials +- [ ] Case studies (problem → solution → results) +- [ ] Client logos +- [ ] User-generated content +- [ ] Review aggregator scores (G2, Trustpilot, etc.) +- [ ] Social media followers/engagement +- [ ] Community size + +### Risk Reversal +- [ ] Money-back guarantee +- [ ] Free trial +- [ ] Free samples/demos +- [ ] Satisfaction guarantee +- [ ] Performance guarantee +- [ ] Easy cancellation +- [ ] No credit card required + +### Data & Specificity +- [ ] Specific results achieved +- [ ] ROI calculations +- [ ] Before/after comparisons +- [ ] Time-to-value metrics +- [ ] Industry benchmarks +- [ ] Research/survey data + +### Process & Methodology +- [ ] Named methodology/system +- [ ] Step-by-step process visualization +- [ ] Behind-the-scenes transparency +- [ ] Quality control standards +- [ ] Security/privacy certifications + +## Asset Acquisition Wishlist + +If you don't have an asset, plan to acquire it: + +| Missing Asset | How to Acquire | Priority | +|---------------|----------------|----------| +| Customer testimonials | Email recent buyers | High | +| Case studies | Interview 3 success stories | High | +| Industry awards | Apply to relevant awards | Medium | +| Media mentions | PR outreach | Medium | + +## Psychological Triggers + +### Scarcity (Use Ethically) +- Limited time offers (genuine deadlines) +- Limited quantity +- Exclusive access +- Seasonal availability + +**Warning**: Fake scarcity destroys trust. Only use real limitations. + +### Social Proof +- "Join 50,000+ marketers" +- Real-time activity ("John from NYC just signed up") +- Testimonials at decision points +- Expert endorsements + +### Authority +- Expert positioning +- Media logos +- Certifications visible +- Specific credentials + +### Reciprocity +- Free valuable content upfront +- Free tools/calculators +- Generous trial periods +- Helpful support + +### Commitment/Consistency +- Micro-commitments (email before credit card) +- Progress indicators +- "You're almost there" messaging +- Previous choices displayed + +### Loss Aversion +- Cost of inaction +- "What you're missing" +- Comparison with competitors' customers +- Before/after contrast + +## The "Proof Sandwich" + +Structure for maximum persuasion: + +1. **Claim**: Make a bold, specific promise +2. **Proof**: Immediately support with evidence +3. **Reinforcement**: Add secondary proof + +Example: +"We increase conversion rates by an average of 47%" (claim) +"Here's how we did it for Company X..." (proof) +"And here's what their CEO says about working with us..." (reinforcement) + +## Placement Principles + +### Above the fold +- Main value proposition +- Primary social proof (logo bar, rating) +- Clear CTA + +### Throughout the page +- Testimonials at objection points +- Data supporting each claim +- Visual proof (screenshots, photos) + +### Decision points +- Guarantees near payment +- Trust badges near forms +- Testimonials near CTAs + +### Bottom of page +- Comprehensive FAQ +- Trust indicators +- Alternative contact options + +## Asset Display Best Practices + +### Logo bars +- 5-7 recognizable logos +- Similar visual treatment +- Relevant to target audience + +### Testimonials +- Photo + Name + Company + Title +- Specific results > vague praise +- Match testimonial to objection + +### Statistics +- Round numbers seem less credible +- "47,832 customers" > "About 50,000" +- Source your data + +### Guarantees +- Make them prominent, not hidden +- Explain what happens if claimed +- Reduce perceived risk of claiming diff --git a/.agents/skills/cro-methodology/references/RESEARCH.md b/.agents/skills/cro-methodology/references/RESEARCH.md new file mode 100644 index 00000000..7afb2b4d --- /dev/null +++ b/.agents/skills/cro-methodology/references/RESEARCH.md @@ -0,0 +1,220 @@ +# CRO Research Methods & Tools + +Don't guess why visitors don't convert. Use these methods to discover the truth. + +## Research Framework + +### Quantitative (What is happening) +- Analytics data +- Heatmaps +- Click tracking +- Funnel analysis +- A/B test results + +### Qualitative (Why it's happening) +- User surveys +- Customer interviews +- Usability testing +- Session recordings +- Support analysis + +**Both are essential.** Quantitative shows WHERE problems are. Qualitative shows WHY they exist. + +## Analytics Analysis + +### Key Reports + +**Funnel Visualization** +- Where do visitors drop off? +- Which steps have highest abandonment? +- Do patterns differ by traffic source? + +**Landing Page Performance** +- Bounce rate by page +- Time on page +- Exit rate vs. bounce rate + +**Traffic Source Analysis** +- Conversion rate by source +- Behavior differences by channel +- Quality vs. quantity of traffic + +**Device/Browser Analysis** +- Mobile vs. desktop conversion +- Browser-specific issues +- Page speed by device + +### Red Flag Metrics + +- Bounce rate > 70% on key pages +- Exit rate spikes at specific steps +- Mobile conversion << desktop (check UX) +- High traffic, low conversion pages +- Long time on checkout pages (confusion) + +## User Surveys + +### On-Site Surveys (Hotjar, Qualaroo) + +**Exit intent surveys**: +- "What stopped you from [action] today?" +- "What's the one thing we could change to make you [action]?" + +**Post-purchase surveys**: +- "What almost stopped you from buying?" +- "What convinced you to choose us?" +- "How would you describe [product] to a friend?" + +**Browsing surveys** (trigger after X seconds): +- "What brought you here today?" +- "Is there anything you can't find?" + +### Email Surveys + +**New customers (within 7 days)**: +- "What was your biggest hesitation before buying?" +- "What finally convinced you?" +- "What's one thing we could improve?" + +**Non-converters (abandoned cart)**: +- "We noticed you didn't complete your order. What stopped you?" +- Keep it to ONE question for higher response rates + +### Survey Best Practices + +1. Ask ONE question (max 2-3) +2. Open-ended > multiple choice for discovery +3. Time triggers thoughtfully +4. Don't annoy—limit frequency +5. Incentivize for longer surveys + +## Usability Testing + +### DIY Testing (5-10 users is enough) + +**Tasks to test**: +1. Find [specific product/information] +2. Complete [primary action] +3. Understand [value proposition] +4. Compare [options/plans] + +**What to observe**: +- Where do users hesitate? +- What do they say aloud? +- What do they click expecting something different? +- What frustrates them? + +### 5-Second Test + +Show page for 5 seconds, then ask: +- "What is this page about?" +- "What action should you take?" +- "What company is this?" + +Tests clarity of value proposition and hierarchy. + +### First-Click Testing + +Give users a task, record where they click first: +- Is it the right element? +- Do different user types behave differently? + +## Session Recordings (Hotjar, FullStory) + +### What to Look For + +**Rage clicks**: Rapid clicking = frustration +**Dead clicks**: Clicking non-clickable elements +**U-turns**: Going back immediately +**Form abandonment**: Which fields cause drop-off +**Scroll depth**: How far do visitors read? + +### Prioritization + +Focus on recordings from: +- High-value pages +- High drop-off points +- Specific user segments (buyers vs. non-buyers) + +## Heatmaps + +### Click Heatmaps +- What gets clicked (and what doesn't)? +- Are CTAs getting attention? +- Are non-clickable elements being clicked? + +### Scroll Heatmaps +- How far do visitors scroll? +- What percentage see key content? +- Where do visitors stop reading? + +### Move Heatmaps +- Where does attention focus? +- What gets ignored? + +### Heatmap Insights → Actions + +| Finding | Action | +|---------|--------| +| CTA not clicked | Test position, color, copy | +| Important content below fold | Move up or add anchor | +| Non-clickable element clicked | Make it clickable or remove | +| Users stop scrolling early | Improve above-fold content | + +## Competitive Analysis + +### What to Analyze + +- Value propositions +- Pricing/positioning +- Social proof used +- Objections addressed +- Risk reversal offers +- Onboarding flows +- Email sequences (sign up!) + +### Competitive O/CO Mining + +1. Read competitor reviews (positive and negative) +2. Note objections customers raise +3. Note what competitors claim as strengths +4. Identify gaps in their approach + +## Customer Interview Guide + +### Who to Interview + +- Recent buyers (why they bought) +- Recent non-buyers (why they didn't) +- Long-term customers (what keeps them) +- Churned customers (why they left) + +### Key Questions + +**Pre-purchase**: +- "What triggered you to look for a solution?" +- "What alternatives did you consider?" +- "What almost stopped you from buying?" +- "What convinced you to choose us?" + +**Post-purchase**: +- "What result have you achieved?" +- "What's been harder than expected?" +- "What would you tell a friend about us?" + +### Interview Tips + +1. Let them talk (don't lead) +2. Ask "why" repeatedly (5 Whys) +3. Get specific examples +4. Record for quotes (with permission) +5. Look for patterns across interviews + +## Research Prioritization + +1. Start with analytics (quick, free) +2. Add on-site survey (1 question) +3. Review existing support/chat logs +4. Watch 10-20 session recordings +5. Run 5 usability tests +6. Deep-dive interviews (ongoing) diff --git a/.agents/skills/cro-methodology/references/funnel-analysis.md b/.agents/skills/cro-methodology/references/funnel-analysis.md new file mode 100644 index 00000000..5da58772 --- /dev/null +++ b/.agents/skills/cro-methodology/references/funnel-analysis.md @@ -0,0 +1,379 @@ +# Funnel Analysis Framework + +Deep methodology for mapping, analyzing, and optimizing conversion funnels. + + +## Table of Contents +1. [Funnel Philosophy](#funnel-philosophy) +2. [Mapping Your Funnel](#mapping-your-funnel) +3. [Blocked Arteries](#blocked-arteries) +4. [Missing Links](#missing-links) +5. [Industry Funnel Patterns](#industry-funnel-patterns) +6. [Funnel Prioritization Framework](#funnel-prioritization-framework) +7. [Funnel Visualization](#funnel-visualization) +8. [Funnel Optimization Checklist](#funnel-optimization-checklist) +9. [Advanced: Multi-Touch Attribution](#advanced-multi-touch-attribution) + +--- + +## Funnel Philosophy + +A funnel isn't just a visualization—it's a diagnostic tool. Every business has a funnel, whether they've mapped it or not. The question is: where is it leaking? + +**Core insight:** Most businesses focus on the top of the funnel (traffic) when the biggest wins are often in the middle (conversion) or bottom (retention/expansion). + +--- + +## Mapping Your Funnel + +### The Basic Funnel Structure + +``` +Awareness → Interest → Consideration → Intent → Evaluation → Purchase → Retention → Advocacy +``` + +### Simplified Business Models + +**E-commerce:** +``` +Visit → View Product → Add to Cart → Begin Checkout → Complete Purchase → Repeat Purchase +``` + +**SaaS:** +``` +Visit → Signup → Onboard → Activate → Engage → Convert (Paid) → Retain → Expand +``` + +**Lead Generation:** +``` +Visit → Lead Magnet → MQL → SQL → Opportunity → Close → Upsell +``` + +**Content/Media:** +``` +Visit → Read/View → Subscribe → Engage → Share → Become Regular +``` + +### Identifying All Steps + +List every step a customer takes from first touch to desired outcome: + +1. **Acquisition touchpoints** - Where do they first hear about you? +2. **Engagement actions** - What do they do before converting? +3. **Conversion moments** - Where do they make commitments? +4. **Value realization** - When do they get what they came for? +5. **Expansion opportunities** - How do they become more valuable? + +--- + +## Blocked Arteries + +A "blocked artery" is a high-traffic path with underperformance—a point where lots of visitors enter but few progress. + +### How to Find Blocked Arteries + +**Step 1: Map traffic volume at each stage** + +``` +Homepage: 10,000 visitors +Product page: 3,000 visitors (30% of traffic) +Add to cart: 600 visitors (20% of product viewers) +Checkout start: 300 visitors (50% of cart adds) +Purchase: 150 visitors (50% of checkout starts) +``` + +**Step 2: Calculate conversion at each step** + +``` +Homepage → Product: 30% +Product → Cart: 20% ← Potential blocked artery +Cart → Checkout: 50% +Checkout → Purchase: 50% +``` + +**Step 3: Compare to benchmarks** + +| Stage | Your Rate | Industry Benchmark | Opportunity | +|-------|-----------|-------------------|-------------| +| Home → Product | 30% | 25-35% | On track | +| Product → Cart | 20% | 5-10% | Actually good | +| Cart → Checkout | 50% | 60-70% | **Blocked artery** | +| Checkout → Purchase | 50% | 70-80% | **Blocked artery** | + +**Step 4: Prioritize by impact** + +Impact = Traffic Volume × Conversion Gap + +``` +Cart → Checkout: 600 × (0.65 - 0.50) = 90 potential conversions +Checkout → Purchase: 300 × (0.75 - 0.50) = 75 potential conversions +``` + +### Common Blocked Arteries + +| Location | Typical Causes | +|----------|----------------| +| Homepage → Category | Unclear value proposition, poor navigation | +| Category → Product | Weak product presentation, too many choices | +| Product → Cart | Missing information, price shock, no urgency | +| Cart → Checkout | Unexpected costs, account requirement, trust issues | +| Checkout → Purchase | Form friction, payment options, shipping cost shock | +| Trial → Paid | Poor onboarding, unclear value, wrong timing | + +--- + +## Missing Links + +A "missing link" is an absent or underutilized funnel stage that leaves value on the table. + +### Common Missing Links + +**Pre-purchase:** +- No retargeting for abandoned visitors +- No email capture before purchase intent +- No comparison tools for researchers +- No social proof at decision points + +**Purchase:** +- No upsell/cross-sell offers +- No subscription/bundle options +- No referral program at purchase +- No installation/setup guidance + +**Post-purchase:** +- No email onboarding sequence +- No check-in at key milestones +- No expansion offers at right time +- No advocacy program for happy customers + +### Missing Link Audit + +| Funnel Stage | Existing Assets | Missing Opportunities | +|--------------|-----------------|----------------------| +| Awareness | Ads, content | Referral program? | +| Interest | Landing pages | Lead magnet? | +| Consideration | Product pages | Comparison tool? | +| Intent | Cart | Save for later? | +| Purchase | Checkout | Order bump? | +| Onboarding | Email 1 | Video tutorial? | +| Retention | None | Check-in sequence? | +| Expansion | None | Usage-based prompts? | +| Advocacy | None | Referral incentive? | + +### Cross-Sell Mapping + +Map products that naturally pair together: + +| Product A | Natural Cross-Sell | When to Offer | +|-----------|-------------------|---------------| +| Running shoes | Socks, insoles | Cart/checkout | +| SaaS subscription | Premium features | After activation | +| Course | Coaching add-on | During course | +| Software | Training | Post-purchase | + +--- + +## Industry Funnel Patterns + +### E-commerce Funnels + +**Standard:** +``` +Visit → Browse → Product → Cart → Checkout → Purchase +``` + +**Enhanced:** +``` +Visit → Browse → Product → Wishlist/Email → Retarget → Cart → Checkout → Upsell → Purchase → Post-purchase email → Review request → Repeat purchase +``` + +**Key metrics:** +- Cart abandonment rate (benchmark: 70%) +- Checkout abandonment rate (benchmark: 25%) +- Repeat purchase rate (benchmark: 25-40%) + +### SaaS Funnels + +**Standard:** +``` +Visit → Trial/Freemium → Activation → Engagement → Conversion +``` + +**Enhanced:** +``` +Visit → Content → Lead magnet → Nurture → Trial → Onboarding → Activation → Engagement → Conversion → Onboarding (paid) → Expansion → Advocacy +``` + +**Key metrics:** +- Trial-to-paid conversion (benchmark: 3-5% freemium, 15-25% free trial) +- Activation rate (varies by product) +- Expansion revenue % (benchmark: 30%+ of revenue) + +### Lead Generation Funnels + +**Standard:** +``` +Visit → Form → Lead → Sales contact → Opportunity → Close +``` + +**Enhanced:** +``` +Visit → Lead magnet → Nurture → Scorecard/Quiz → MQL → SDR qualify → Demo → SQL → Proposal → Close → Onboarding → Expansion +``` + +**Key metrics:** +- Lead-to-MQL conversion (benchmark: 20-30%) +- MQL-to-SQL conversion (benchmark: 30-50%) +- SQL-to-close rate (benchmark: 20-40%) + +### Subscription/Membership Funnels + +**Standard:** +``` +Visit → Free content → Subscribe → Retain +``` + +**Enhanced:** +``` +Visit → Free content → Email opt-in → Free trial → Subscribe → Onboard → Engage → Retain → Annual upgrade → Advocacy +``` + +**Key metrics:** +- Free-to-paid conversion (benchmark: 2-5%) +- Monthly churn rate (benchmark: 3-7%) +- Annual vs. monthly mix (benchmark: 30%+ annual) + +--- + +## Funnel Prioritization Framework + +### Calculate Opportunity Value + +For each potential improvement: + +``` +Opportunity = (Current Volume) × (Conversion Gap) × (Revenue per Conversion) +``` + +**Example:** +``` +Current: 1,000 visitors, 2% conversion, $100/conversion = $2,000 revenue +Potential: 1,000 visitors, 3% conversion, $100/conversion = $3,000 revenue +Opportunity value: $1,000/month = $12,000/year +``` + +### Prioritization Matrix + +| Opportunity | Volume | Gap | Value | Ease | Priority | +|-------------|--------|-----|-------|------|----------| +| Checkout abandonment | 500/mo | 25% | $125 | Medium | High | +| Add cross-sell | 200/mo | 30% | $20 | Easy | High | +| Reduce form fields | 1000/mo | 10% | $50 | Easy | High | +| Redesign homepage | 5000/mo | 2% | $100 | Hard | Medium | +| Add video | 300/mo | 15% | $100 | Medium | Medium | + +### The 80/20 Rule in Funnels + +Typically: +- 80% of revenue comes from 20% of the funnel stages +- 80% of drop-off happens at 20% of the steps +- 80% of improvement potential is in 20% of the pages + +**Focus ruthlessly on the high-impact stages before optimizing everything.** + +--- + +## Funnel Visualization + +### Basic Funnel Chart + +``` +┌─────────────────────────────────────────┐ 10,000 +│ Website Visits │ +├───────────────────────────────┐ │ 3,000 (30%) +│ Product Page Views │ +├─────────────────────┐ │ │ 600 (20%) +│ Add to Cart │ +├───────────────┐ │ │ │ 300 (50%) +│ Checkout │ +├─────────┐ │ │ │ │ 150 (50%) +│ Purchase│ +└─────────┘ +``` + +### Leakage Analysis + +At each stage, map where users go instead: + +``` +Product Page (3,000 visitors) +├─→ Add to Cart: 600 (20%) +├─→ Exit site: 1,500 (50%) +├─→ Browse other products: 600 (20%) +├─→ Check reviews/FAQ: 200 (7%) +└─→ Contact support: 100 (3%) +``` + +**Insight:** 50% exit from product page—that's the primary leak to investigate. + +--- + +## Funnel Optimization Checklist + +### Before Optimizing + +- [ ] Have you mapped the complete funnel? +- [ ] Do you have baseline conversion rates at each stage? +- [ ] Have you identified the biggest blocked arteries? +- [ ] Have you audited for missing links? +- [ ] Do you know your industry benchmarks? +- [ ] Have you calculated opportunity values? + +### During Optimization + +- [ ] Are you testing bold changes, not tweaks? +- [ ] Are you measuring the right metrics? +- [ ] Are you waiting for statistical significance? +- [ ] Are you documenting learnings? + +### After Optimization + +- [ ] Did conversion improve at the target stage? +- [ ] Did downstream metrics also improve? +- [ ] Did any metrics unexpectedly decrease? +- [ ] Can this learning apply to other funnels? + +--- + +## Advanced: Multi-Touch Attribution + +### The Problem + +Customers don't convert in a straight line. They might: +1. See a Facebook ad +2. Google your brand +3. Read a blog post +4. Leave +5. Get retargeted +6. Return via email +7. Convert + +Which touchpoint gets credit? + +### Attribution Models + +| Model | Description | Best For | +|-------|-------------|----------| +| First-touch | First interaction gets 100% | Brand awareness campaigns | +| Last-touch | Final interaction gets 100% | Direct response | +| Linear | Equal credit to all touches | Understanding journey | +| Time-decay | Recent touches get more credit | Short sales cycles | +| Position-based | 40% first, 40% last, 20% middle | Balanced view | +| Data-driven | Algorithm assigns based on data | Sophisticated analysis | + +### Practical Recommendation + +1. Start with last-touch (simplest) +2. Add first-touch to understand acquisition +3. Graduate to position-based for balanced view +4. Only use data-driven with sufficient volume diff --git a/.agents/skills/cro-methodology/references/testing-methodology.md b/.agents/skills/cro-methodology/references/testing-methodology.md new file mode 100644 index 00000000..9be57e33 --- /dev/null +++ b/.agents/skills/cro-methodology/references/testing-methodology.md @@ -0,0 +1,343 @@ +# CRO Testing Methodology + +Deep-dive into experiment design, statistical rigor, and test prioritization from the CRE Methodology. + + +## Table of Contents +1. [The Philosophy of Bold Testing](#the-philosophy-of-bold-testing) +2. [A/B Testing vs. Multivariate Testing](#ab-testing-vs-multivariate-testing) +3. [Statistical Significance](#statistical-significance) +4. [ICE Prioritization Framework](#ice-prioritization-framework) +5. [Test Documentation](#test-documentation) +6. [When Tests Fail](#when-tests-fail) +7. [CRO Team Dynamics](#cro-team-dynamics) +8. [Testing Platform Comparison](#testing-platform-comparison) + +--- + +## The Philosophy of Bold Testing + +### Why "Meek Tweaks" Fail + +Most A/B tests fail because they're too small to detect. Button color changes, minor copy tweaks, and micro-optimizations suffer from: + +1. **Insufficient sample size** - Small changes require massive traffic to reach significance +2. **Interaction effects** - Minor changes get lost in noise +3. **Opportunity cost** - Time spent on 2% wins could find 200% wins + +**Rule: Test big changes that could double conversion, not small changes that might move it 5%.** + +### The 10x Mindset + +Before any test, ask: "Could this 10x our results?" If not, is it worth testing? + +- **Worth testing:** Complete page redesign, new value proposition, fundamentally different offer +- **Not worth testing:** Button color, font size, image swap + +--- + +## A/B Testing vs. Multivariate Testing + +### A/B Testing (Split Testing) + +Compare two (or more) complete versions against each other. + +| Aspect | Details | +|--------|---------| +| **Best for** | Testing big concepts, page redesigns, offers | +| **Traffic needed** | Lower (split between 2-4 variants) | +| **Insights** | Which version wins overall | +| **Limitation** | Doesn't show which elements contributed | + +**When to use:** +- You have a hypothesis about a major change +- Traffic is limited +- You're comparing conceptual approaches + +### Multivariate Testing (MVT) + +Test multiple elements simultaneously to find optimal combination. + +| Aspect | Details | +|--------|---------| +| **Best for** | Optimizing elements after winning concept proven | +| **Traffic needed** | Much higher (combinations multiply) | +| **Insights** | Which specific elements drive results | +| **Limitation** | Requires significant traffic | + +**When to use:** +- You have a winning page to optimize further +- High traffic (100k+ monthly visitors) +- Clear, isolated elements to test + +### Traffic Requirements + +**A/B Test:** +``` +Minimum sample per variant = 250-500 conversions +For 2 variants with 5% conversion: 10,000-20,000 visitors needed +``` + +**Multivariate Test:** +``` +Combinations = (Options for Element 1) × (Options for Element 2) × ... +Example: 3 headlines × 3 images × 2 CTAs = 18 combinations +Each combination needs 250+ conversions = 90,000+ conversions total +``` + +**Recommendation:** Start with A/B tests. Only move to MVT when you have: +- Proven winning page concept +- 100k+ monthly visitors +- Mature testing program + +--- + +## Statistical Significance + +### What It Means + +Statistical significance tells you: "How likely is this result due to chance vs. a real effect?" + +**Industry standard:** 95% confidence (p-value < 0.05) +- 95% confident the difference is real +- 5% chance it's random noise + +### Common Mistakes + +**1. Peeking and stopping early** + +Checking results daily and stopping when you see a winner leads to false positives. + +- **Wrong:** "We're at 95% confidence after 3 days—ship it!" +- **Right:** Pre-determine sample size and test duration; don't stop early + +**2. Calling tests with insufficient data** + +| Visitors | Conversions | Can you call it? | +|----------|-------------|------------------| +| 500 | 15 vs 20 | No | +| 5,000 | 150 vs 200 | Possibly | +| 50,000 | 1,500 vs 2,000 | Yes | + +**3. Ignoring practical significance** + +A statistically significant 0.1% lift isn't worth implementation complexity. + +**4. Multiple comparison problem** + +Testing 20 variants? One will show "significance" by chance alone. + +### Sample Size Calculation + +Before testing, calculate required sample size: + +**Inputs needed:** +- Baseline conversion rate +- Minimum detectable effect (MDE) you care about +- Statistical power (typically 80%) +- Significance level (typically 95%) + +**Rule of thumb:** +``` +For 5% baseline, 20% relative lift detection: +~25,000 visitors per variant needed + +For 5% baseline, 50% relative lift detection: +~4,000 visitors per variant needed +``` + +**Key insight:** The smaller the effect you want to detect, the more traffic you need. This is why bold changes are better—they're detectable with less traffic. + +### Test Duration + +**Minimum test duration:** +- At least 1 full business cycle (typically 1-2 weeks) +- Include weekdays AND weekends +- Account for seasonality + +**Why?** +- Visitor behavior differs by day of week +- Friday buyers differ from Monday researchers +- Monthly cycles affect B2B especially + +--- + +## ICE Prioritization Framework + +Prioritize test ideas using ICE scores: + +### Impact (1-10) +"If this wins, how big would the impact be?" + +| Score | Impact Level | +|-------|--------------| +| 10 | Could double conversion rate | +| 7-9 | Major improvement (30-50%+) | +| 4-6 | Moderate improvement (10-30%) | +| 1-3 | Minor improvement (<10%) | + +### Confidence (1-10) +"How confident are we this will work?" + +| Score | Confidence Level | +|-------|------------------| +| 10 | Proven in research, worked before | +| 7-9 | Strong research supports it | +| 4-6 | Reasonable hypothesis | +| 1-3 | Gut feeling, unvalidated | + +### Ease (1-10) +"How easy is this to implement and test?" + +| Score | Ease Level | +|-------|------------| +| 10 | Text change only | +| 7-9 | Design change, no dev needed | +| 4-6 | Requires development | +| 1-3 | Major technical lift | + +### ICE Score Calculation + +``` +ICE Score = (Impact + Confidence + Ease) / 3 +``` + +Or weighted: +``` +ICE Score = (Impact × 2 + Confidence × 1.5 + Ease × 1) / 4.5 +``` + +### Sample Prioritization + +| Test Idea | Impact | Confidence | Ease | Score | +|-----------|--------|------------|------|-------| +| New headline from customer research | 8 | 9 | 10 | 9.0 | +| Add video testimonial | 7 | 7 | 6 | 6.7 | +| Redesign checkout flow | 9 | 6 | 3 | 6.0 | +| Change button color | 2 | 2 | 10 | 4.7 | + +--- + +## Test Documentation + +### Before the Test + +Document: +1. **Hypothesis:** "If we [change X], then [metric Y] will improve because [reason based on research]" +2. **Primary metric:** One metric that determines winner +3. **Secondary metrics:** Additional metrics to monitor +4. **Guardrail metrics:** Metrics that shouldn't decrease +5. **Sample size requirement** +6. **Test duration** +7. **Traffic allocation** + +### After the Test + +Document: +1. **Results:** Raw numbers, conversion rates, confidence interval +2. **Statistical significance:** p-value, confidence level +3. **Practical significance:** Is the lift worth implementing? +4. **Learnings:** What does this teach us about our customers? +5. **Next steps:** Ship winner, iterate, or abandon? + +### Learnings Database + +Every test should add to organizational knowledge: + +| Test | Hypothesis | Result | Learning | Applicable to | +|------|------------|--------|----------|---------------| +| Homepage headline A/B | Customer language converts better | Winner: +27% | Customers care about outcomes, not features | All landing pages | +| Form length test | Shorter forms convert better | Loser: no diff | Our audience expects detailed forms | Lead gen pages | + +--- + +## When Tests Fail + +### Types of "Failure" + +**1. No winner (inconclusive)** +- Sample size too small +- Effect size too small to detect +- Test needed to run longer + +**2. Control wins** +- New version is worse +- Hypothesis was wrong +- Still a learning! + +**3. Technical problems** +- Tracking broke +- Experience differed from plan +- Sample contamination + +### What to Do + +1. **Document the learning** - "We learned customers prefer X" +2. **Investigate why** - Go back to research +3. **Don't give up on the page** - The opportunity exists, you just haven't found the solution +4. **Try a bolder change** - Maybe the change wasn't big enough + +**Critical insight:** A failed test that teaches you something is more valuable than a winning test you don't understand. + +--- + +## CRO Team Dynamics + +### Roles in a CRO Program + +| Role | Responsibility | +|------|----------------| +| **CRO Lead** | Strategy, prioritization, stakeholder management | +| **Researcher** | User research, surveys, analytics analysis | +| **Designer** | Wireframes, mockups, user flows | +| **Developer** | Test implementation, technical QA | +| **Analyst** | Results analysis, statistical rigor | + +### Getting Stakeholder Buy-In + +**Common objections:** + +| Objection | Counter | +|-----------|---------| +| "We already know what works" | "Then testing will confirm it quickly" | +| "Testing takes too long" | "Shipping wrong things costs more" | +| "Our traffic is too low" | "Then we test bigger changes" | +| "The CEO wants X" | "Let's test to validate the idea" | + +**Building credibility:** +1. Start with quick wins (high-traffic pages, obvious problems) +2. Document and share learnings widely +3. Quantify impact in revenue terms +4. Build testing into the culture, not just a project + +### Test Velocity + +**Goal:** Increase valid tests per month over time. + +| Maturity | Tests/Month | Characteristics | +|----------|-------------|-----------------| +| Beginner | 1-2 | Manual processes, ad-hoc | +| Developing | 4-6 | Established backlog, regular cadence | +| Advanced | 10-20 | Parallel testing, mature process | +| Expert | 20+ | Multiple simultaneous tests, automated | + +--- + +## Testing Platform Comparison + +| Platform | Best For | Limitations | +|----------|----------|-------------| +| Google Optimize | Beginners, free tier | Sunsetting, limited features | +| VWO | Mid-market, visual editor | Can be slow, limited targeting | +| Optimizely | Enterprise, complex tests | Expensive, learning curve | +| LaunchDarkly | Dev-centric, feature flags | Not optimized for marketing | +| Custom | Full control | Development cost | + +### Key Features to Look For + +- Visual editor for non-developers +- Robust statistical engine +- Segment targeting +- Integrations (analytics, CDP, etc.) +- Flicker prevention +- Mutually exclusive experiments diff --git a/.agents/skills/crossing-the-chasm/SKILL.md b/.agents/skills/crossing-the-chasm/SKILL.md new file mode 100644 index 00000000..9e0ed5de --- /dev/null +++ b/.agents/skills/crossing-the-chasm/SKILL.md @@ -0,0 +1,213 @@ +--- +name: crossing-the-chasm +description: 'Navigate the technology adoption lifecycle from early adopters to mainstream market. Use when the user mentions "crossing the chasm", "beachhead segment", "whole product", "early adopters vs mainstream", "tech go-to-market", "bowling pin strategy", "technology adoption lifecycle", "pragmatist buyers", "growth stalled after early adopters", or "our go-to-market plan". Also trigger when planning go-to-market for a technical product. Covers the D-Day analogy, bowling-pin strategy, the tornado, and positioning against incumbents. For product positioning, see obviously-awesome. For new market creation, see blue-ocean-strategy.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Crossing the Chasm Framework + +Strategic framework for marketing and selling disruptive technology products, particularly the transition from early adopters to mainstream customers. + +## Core Principle + +**There is a chasm between early adopters and the mainstream market.** Most tech companies fail not because they can't build great products, but because they can't cross from visionaries who love new technology to pragmatists who just want solutions that work. The two groups want fundamentally different things -- what wins over innovators actively repels the early majority -- so you must change your strategy, and your whole product, to cross. + +If the product is modern PLG/freemium B2B SaaS, read [references/b2b-saas.md](references/b2b-saas.md) first -- it remaps every step below (the chasm, beachhead, whole product, metrics) for self-serve trials, free tiers, and the false-signal trap where 1,000 free users looks like a crossing but isn't. + +## Scoring + +**Goal: 10/10.** Score any tech go-to-market by the Quick Diagnostic at the end: count the rows answered "yes" and map the 7 rows onto a 0-10 scale (roughly 1.4 points per satisfied row). + +- **9-10:** single dominable beachhead chosen, 10+ in-segment references, whole product complete via partners, evolution-not-revolution positioning, pragmatist-aligned channel -- adoption is accelerating. You've crossed. +- **5-6:** beachhead picked but whole product or references still thin, or positioning still reads "revolutionary." You're mid-chasm; ship the missing whole-product layers and case studies. +- **<=3:** multiple beachheads (or none), visionary messaging, MVP-grade product. Classic early-market tactics aimed at the mainstream -- the most common reason to stall. + +Report the score, name the failing diagnostic rows, and give the fix for each. + +## The Technology Adoption Life Cycle + +``` +Innovators → Early Adopters → [CHASM] → Early Majority → Late Majority → Laggards + 2.5% 13.5% 34% 34% 16% +``` + +**The Chasm:** The gap between early adopters (13.5%) and early majority (34%) -- where most tech products die. + +### The Five Buyer Groups + +| Segment | % Market | Psychology | What They Buy | What They Need | +|---------|----------|------------|---------------|----------------| +| **Innovators** | 2.5% | Technology enthusiasts | The newest, coolest tech | Product exists, technical specs | +| **Early Adopters** | 13.5% | Visionaries seeking advantage | Change, revolution, competitive edge | Vision, big potential, strategic value | +| **[THE CHASM]** | — | — | — | — | +| **Early Majority** | 34% | Pragmatists | Productivity improvements | Whole product, references, de-risked | +| **Late Majority** | 34% | Conservatives | Avoid being left behind | Commodity, support, low risk | +| **Laggards** | 16% | Skeptics | Only when forced | Cheap, simple, necessary | + +**Critical insight:** Early adopters and early majority look similar but want opposite things: + +| Early Adopters (Visionaries) | Early Majority (Pragmatists) | +|------------------------------|------------------------------| +| Want to be first | Want proven solutions | +| Tolerate bugs and workarounds | Need it to "just work" | +| Buy the future vision | Buy present value | +| Need no references | Need references from peers | +| Want custom solutions, high risk tolerance | Want standards, low risk tolerance | + +**Why this matters:** You can't market to both simultaneously -- visionary testimonials scare off pragmatists. + +See: [references/buyer-segments.md](references/buyer-segments.md) when you need to identify which group a specific prospect belongs to, or to write segment-specific messaging -- it has full psychographics and buying triggers per group. + +**The reference catch-22:** Pragmatists won't buy without references from other pragmatists -- but none exist until someone crosses first. This is *why* the chasm is a chasm and not a slope: the social proof the early majority requires cannot accumulate gradually. Breaking it is the whole game (Steps 1-2 below). + +## The D-Day Strategy: Crossing the Chasm + +**Bad approach:** Try to be everything to everyone (stall in the chasm). **Good approach:** Target a single beachhead, dominate it, expand from a position of strength. + +### Step 1: Target the Point of Attack + +**Choose a single, narrowly defined market segment.** + +**Beachhead characteristics:** specific ("orthopedic surgical centers with 5-10 surgeons", not "healthcare"); urgent, expensive pain; accessible via known channels; a compelling reason to buy (you're 10x better for their problem); whole-product potential via partners; vocal reference potential. + +| Criteria | Good Beachhead | Bad Beachhead | +|----------|----------------|---------------| +| **Size** | Big enough to matter, small enough to dominate | Too small to build on, or too big to own | +| **Pain** | Urgent, expensive problem | Nice-to-have | +| **Access** | Clear channels to reach | Scattered, hard to reach | +| **Competition** | Weak or non-existent | Entrenched incumbents | +| **Word-of-mouth** | They talk to each other | Siloed, isolated | + +**Example (Salesforce):** not "CRM for all businesses" but "sales force automation for inside sales teams at B2B SaaS startups." + +**Process:** Brainstorm 20+ segments, score each against the criteria, choose ONE (resist keeping options open), commit to dominating it. + +See: [references/beachhead-selection.md](references/beachhead-selection.md) when running the brainstorm-and-score step above -- it has the scoring matrix, weighting, and the target-customer characterization worksheet to pick the one segment. + +### Step 2: Assemble the Invasion Force + +**Create the "whole product" for your beachhead segment.** + +Whole product layers: Generic (what you ship) → Expected (minimum viable) → Augmented (what pragmatists actually need) → Potential (what it could become). + +**Example: marketing automation software** + +| Layer | What It Includes | +|-------|------------------| +| **Generic** | Email sending, list management | +| **Expected** | Templates, analytics, API | +| **Augmented** | CRM integration, training, support, services, best-practice playbooks | +| **Potential** | AI optimization, personalization, account-based marketing | + +**Critical:** The early majority buys the augmented product; ship only the generic and they won't buy. + +**Whole product checklist:** +- [ ] Core technology (your product) +- [ ] Complementary products/services (integrations, partner solutions) +- [ ] Installation and setup (onboarding, migration) +- [ ] Training, support, documentation, best practices +- [ ] Industry-specific adaptations +- [ ] Risk mitigation (security, compliance, SLAs) + +**Partnerships:** Identify gaps between generic and augmented, partner with companies that fill them, go to market jointly for the beachhead. + +See: [references/whole-product.md](references/whole-product.md) when mapping your gaps -- it extends the layers above with a 12-row gap-analysis matrix, the 80% rule, support-tier SLAs, and a planning canvas. + +### Step 3: Define the Battle + +**Position against the competition.** + +**Positioning formula:** +- For [target customer] +- Who [statement of need/opportunity] +- Our product is a [product category] +- That [statement of key benefit] +- Unlike [primary competitive alternative] +- Our product [statement of primary differentiation] + +**Example (early Workday):** For mid-market companies who need modern HR and finance systems, Workday is a cloud-based ERP that delivers consumer-grade UX and fast implementation. Unlike Oracle and SAP, it requires no IT infrastructure and deploys in months, not years. + +**Competitive positioning:** The market alternative is often NOT a direct competitor -- it's manual processes, spreadsheets, or legacy systems. Differentiate on a dimension you dominate and make the incumbent's strength irrelevant: Salesforce's "No software" positioning turned feature-rich Siebel's complexity into a weakness. + +See: [references/positioning.md](references/positioning.md) when filling in the formula above or choosing the competitive alternative to displace -- it has the claim-and-evidence structure and the "make the incumbent's strength irrelevant" patterns. + +### Step 4: Launch the Invasion + +**Execute the go-to-market strategy.** + +| Customer Type | How They Buy | Sales Strategy | +|---------------|--------------|----------------| +| **Early adopters** | Direct, evangelical CEO | Direct sales, founder-led | +| **Early majority** | Risk-averse, need proof | Channel partners, references, content marketing | +| **Late majority** | Commodity, low-touch | Self-service, inside sales | + +**For crossing (early majority):** lead with references and case studies; message whole-product completeness, ease, and low risk; position as evolution ("Better X", not "new category"); prove with ROI calculators, free trials, pilots; sell through channels pragmatists trust (analysts, integrators, consultants). + +**Messaging shift:** + +| Early Adopter Messaging | Early Majority Messaging | +|-------------------------|--------------------------| +| "Revolutionary new approach" | "Proven solution for [problem]" | +| "Be the first" | "Join 500 companies like yours" | +| "Change everything" | "Improve [specific metric] by X%" | +| "Visionary" | "Pragmatic" | + +See: [references/go-to-market.md](references/go-to-market.md) when building the launch plan -- it details channel selection by buyer type, the reference-and-case-study engine, and pricing/pilot tactics for pragmatists. + +## Bowling Pin Strategy + +**After dominating the beachhead, expand to adjacent segments** -- each pin knocks down the next: Beachhead → Adjacent #1 → Adjacent #2 → Adjacent #3. + +**Adjacency criteria:** similar needs (whole product transfers), reference credibility (beachhead customers influence the adjacent segment), incremental effort (don't start from scratch). + +**Example (Salesforce):** inside sales at tech startups → inside sales at all B2B companies → all sales teams → customer service → marketing → full CRM platform. + +**Anti-pattern:** Jumping to distant segments before dominating the beachhead. + +See: [references/expansion.md](references/expansion.md) when sequencing your next 2-3 segments -- adjacency scoring and the bowling-pin ordering rules. For full worked arcs (Salesforce, VMware, Zoom, Atlassian) and stuck-in-the-chasm failures (Palm, Segway), see [references/case-studies.md](references/case-studies.md) when you need a pattern-match for your own situation. + +## The Tornado: After the Chasm + +**Once you cross, demand accelerates (the "tornado"):** rapid mainstream adoption, a shift from solution selling to product selling, commodity dynamics, and market-leader consolidation. + +**Strategic shift:** before the chasm -- whole product, customization, high touch; during the tornado -- standardization, scalability, distribution. + +**Gorilla/chimp/monkey dynamics:** the gorilla (market leader, 80%+ share) takes most of the profit; chimps (strong #2-#3) survive in niches; monkeys struggle. Become the gorilla in your beachhead, then expand. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|------| +| **Selling to early majority like early adopters** | Wrong messaging, wrong product | Build whole product, emphasize proof | +| **Multiple beachheads** | Spread too thin, own nothing | Choose ONE segment, dominate it | +| **Incomplete whole product** | Pragmatists won't buy | Partner to fill gaps | +| **"Revolutionary" positioning** | Scares off early majority | Frame as evolution, proven solution | +| **Skipping references** | No social proof for pragmatists | Invest in case studies, testimonials | + +## Quick Diagnostic + +Audit any tech go-to-market, and re-run it as the completion gate before declaring the chasm crossed. Each "If No" is a chasm symptom; act on the failing rows first. + +| Question | If No | Action | +|----------|-------|--------| +| Have we chosen a single, narrowly defined beachhead with an urgent, expensive problem? | You're in the chasm | Define one narrow target market; resist multiple beachheads | +| Can we plausibly dominate this segment? | Wrong beachhead | Choose a narrower or different segment | +| Do we have 10+ reference customers from that exact segment? | Pragmatists won't buy | Build lighthouse customers and case studies | +| Is the whole product complete -- partnerships in place to fill the gaps? | Product won't meet pragmatist needs | Identify generic-to-augmented gaps, partner to fill them | +| Does positioning emphasize proven value over revolution? | Wrong message for the early majority | Reframe: evolution, not revolution | +| Is the distribution channel aligned with pragmatist buying behavior? | You reach visionaries, not pragmatists | Sell through analysts, integrators, references, channel | +| Are adoption metrics accelerating (entering the tornado)? | Still stuck before the chasm | Re-check the rows above -- something is still early-market | + +## Further Reading + +For the complete methodology: + +- [*"Crossing the Chasm"*](https://www.amazon.com/Crossing-Chasm-3rd-Disruptive-Mainstream/dp/0062292986?tag=wondelai00-20) by Geoffrey A. Moore (3rd Edition) +- [*"Inside the Tornado"*](https://www.amazon.com/Inside-Tornado-Strategies-Developing-Hypergrowth/dp/0887307760?tag=wondelai00-20) by Geoffrey A. Moore (sequel: managing hypergrowth) + +## About the Author + +**Geoffrey A. Moore** is a consultant, venture partner, and author whose work at The Chasm Group and Chasm Institute has shaped go-to-market strategy for enterprise technology companies for over 30 years. *Crossing the Chasm* has sold over a million copies and is required reading at business schools and tech companies worldwide. diff --git a/.agents/skills/crossing-the-chasm/references/b2b-saas.md b/.agents/skills/crossing-the-chasm/references/b2b-saas.md new file mode 100644 index 00000000..242ddd39 --- /dev/null +++ b/.agents/skills/crossing-the-chasm/references/b2b-saas.md @@ -0,0 +1,360 @@ +# Crossing the Chasm for Modern B2B SaaS + +Geoffrey Moore wrote Crossing the Chasm in 1991, when enterprise software was sold on CDs, installed on-premise, and purchased through multi-year license agreements. The core framework remains deeply relevant, but the mechanics of how B2B SaaS companies cross the chasm have transformed. Product-led growth, freemium models, community-driven adoption, and API-first architectures create new paths across the chasm -- and new ways to get stuck in it. + +This reference applies the Crossing the Chasm framework to the realities of modern B2B SaaS. + + +## Table of Contents +1. [How SaaS Changes the Adoption Curve](#how-saas-changes-the-adoption-curve) +2. [Product-Led Growth and the Chasm](#product-led-growth-and-the-chasm) +3. [How Freemium Changes the Adoption Curve](#how-freemium-changes-the-adoption-curve) +4. [Modern Beachhead Selection for SaaS](#modern-beachhead-selection-for-saas) +5. [Whole Product in the API/Integration Era](#whole-product-in-the-apiintegration-era) +6. [Community-Led Growth as Chasm-Crossing Strategy](#community-led-growth-as-chasm-crossing-strategy) +7. [Modern Metrics for Tracking Adoption Lifecycle Position](#modern-metrics-for-tracking-adoption-lifecycle-position) +8. [Case Studies: Modern SaaS Through the Chasm Lens](#case-studies-modern-saas-through-the-chasm-lens) +9. [The Modern SaaS Chasm-Crossing Playbook](#the-modern-saas-chasm-crossing-playbook) + +--- + +## How SaaS Changes the Adoption Curve + +### Traditional Software vs SaaS Adoption Dynamics + +| Dimension | Traditional Enterprise Software | Modern B2B SaaS | +|-----------|-------------------------------|-----------------| +| Discovery | Sales rep outreach, RFP | Self-serve trial, peer recommendation, content | +| Evaluation | Vendor demo, POC | Free tier, self-serve onboarding | +| Purchase | Annual license, procurement | Monthly subscription, credit card | +| Adoption | Big-bang deployment | Gradual team-by-team rollout | +| Expansion | Upsell through account manager | Usage growth, team virality, feature upgrades | +| Switching cost | Very high (data migration, retraining) | Lower (but still significant at scale) | + +### What This Means for the Chasm + +The chasm still exists in SaaS, but it manifests differently: + +**Lower barrier to trial, same barrier to commitment.** Pragmatists will try your product (free tier), but they won't commit their team, data, and workflows to it without the same proof and whole product they've always required. + +**Bottom-up adoption creates a false signal.** Having 1,000 free users who signed up because it's free is not crossing the chasm. Crossing the chasm means pragmatist organizations are standardizing on your product and paying for it. + +**Faster feedback loops.** You can see adoption data in real-time, which means you can identify your beachhead empirically (who actually uses the product deeply?) rather than purely theoretically. + +## Product-Led Growth and the Chasm + +### How PLG Relates to the Adoption Lifecycle + +Product-led growth (PLG) is a powerful chasm-crossing mechanism when applied correctly. Here's how PLG maps to the adoption lifecycle: + +| Stage | PLG Mechanism | Adoption Segment | +|-------|-------------|-----------------| +| Free sign-up | Individual discovers and tries product | Innovators and some Early Adopters | +| Active use (individual) | Single user gets value | Innovators | +| Team invitation | User invites colleagues | Early Adopters (vision of team value) | +| Team standardization | Team adopts as primary tool | Early Majority (pragmatist team lead) | +| Organization rollout | IT/procurement formalizes | Early Majority (pragmatist organization) | +| Enterprise contract | Multi-year deal with SLAs | Late Majority | + +**The PLG chasm sits between "team invitation" and "team standardization."** Getting individuals to use your product is not crossing the chasm. Getting pragmatist team leads to make it the standard tool is. + +### PLG Chasm-Crossing Checklist + +- [ ] Self-serve onboarding gets a team (not just an individual) to value within one session +- [ ] Admin controls exist for team leads to manage members and permissions +- [ ] Usage data is visible to help team leads justify the tool to their organization +- [ ] Upgrade path from free to paid is clear and tied to team-level value +- [ ] Integration with the team's existing workflow tools is native +- [ ] Security and compliance features satisfy IT review (SSO, SCIM, audit logs) +- [ ] Reference customers exist at the team/organization level, not just individual level + +## How Freemium Changes the Adoption Curve + +### The Freemium Trap + +Freemium is a powerful distribution mechanism, but it can disguise chasm problems: + +**Vanity metrics:** 100,000 free accounts feels like traction, but if conversion to paid is 0.5% and all paying customers are innovators, you haven't crossed anything. + +**Wrong segment signal:** Free users skew toward innovators and price-sensitive small teams. Their usage patterns may not represent your beachhead segment's needs. + +**Delayed chasm recognition:** Revenue grows slowly but steadily from self-serve conversions, masking the fact that pragmatist organizations aren't adopting. + +### Freemium as a Chasm-Crossing Tool + +When used strategically, freemium accelerates chasm crossing: + +**Built-in trial:** Pragmatists who would never agree to a sales call will try a free product. This lowers the barrier to evaluation. + +**Usage data as proof:** When a pragmatist's team is already using the free version, the proof of value is internal, not external. "Your team already uses this 40 hours per week" is more compelling than any case study. + +**Viral expansion within organizations:** One team adopts, adjacent teams see it working, adoption spreads. This is the bowling pin strategy happening organically within a single account. + +### Freemium Conversion Framework for Pragmatists + +| Free Tier | Paid Tier | Enterprise Tier | +|-----------|-----------|-----------------| +| Individual or small team use | Team-level features + admin controls | Organization-wide + security + support | +| Enough value to prove the concept | Enough value to standardize on | Complete whole product | +| No time limit | Monthly or annual | Annual with SLAs | +| Self-serve support only | Priority support | Dedicated CSM | +| Limited integrations | Full integrations | Custom integrations + API | +| Basic security | SSO, RBAC | SOC 2, HIPAA, custom security reviews | + +**Key principle:** The free-to-paid boundary should align with the individual-to-team transition. Individual value is free; team value is paid. + +## Modern Beachhead Selection for SaaS + +### Using Product Data to Identify Your Beachhead + +Unlike traditional software companies that had to guess their beachhead, SaaS companies have data: + +**Step 1: Analyze your highest-engagement users** +- Who uses the product daily? +- Who uses the most features? +- Who invites the most team members? +- Who has the highest retention (12+ months)? + +**Step 2: Find the common attributes** +- What industry are they in? +- What company size? +- What role/function? +- What use case drove adoption? +- How did they discover you? + +**Step 3: Validate the segment** +- Are these users willing to pay (or already paying)? +- Do they talk to each other (conferences, communities, Slack groups)? +- Can you build the whole product for them? +- Is the segment large enough to sustain growth? + +### Example: Identifying a SaaS Beachhead from Data + +**Product:** Workflow automation tool + +**Data analysis reveals:** +- Highest engagement: Marketing operations teams at B2B SaaS companies (50-500 employees) +- Use case: Automating lead routing and campaign workflows +- Retention: 94% annual retention in this cohort vs 72% overall +- Expansion: These teams invite 3x more colleagues than average +- Revenue: Average contract value 2x overall average + +**Beachhead decision:** Marketing operations teams at mid-market B2B SaaS companies. + +This is more precise and validated than any pre-data beachhead selection could be. + +## Whole Product in the API/Integration Era + +### The Modern Whole Product Stack + +For SaaS products, the whole product increasingly means the integration and ecosystem layer: + +| Layer | Traditional Whole Product | Modern SaaS Whole Product | +|-------|--------------------------|--------------------------| +| Core | Installed software | Cloud application | +| Expected | Manual, documentation | Self-serve onboarding, help docs, basic integrations | +| Augmented | Custom implementation, consultants | Native integrations, APIs, templates, marketplace | +| Potential | Future versions | Platform, developer ecosystem, AI features | + +### Integration as Competitive Moat + +For pragmatist SaaS buyers, integrations are not nice-to-have -- they are the primary evaluation criterion after core functionality: + +**The integration hierarchy for pragmatists:** +1. Native integrations with their critical tools (must work out of the box) +2. iPaaS support (Zapier, Make, Workato) for custom workflows +3. Open API for custom development +4. Webhook support for event-driven architectures + +**Beachhead-specific integration strategy:** +- Identify the 3-5 tools your beachhead segment uses daily +- Build native, maintained integrations with each +- Create segment-specific workflow templates using these integrations +- These integrations ARE the whole product for modern SaaS + +### Example: Whole Product for Marketing Ops Beachhead + +| Component | What's Needed | Priority | +|-----------|--------------|----------| +| Native integration: Salesforce | Bi-directional sync, field mapping, lead routing | Critical | +| Native integration: HubSpot | Campaign sync, contact management | Critical | +| Native integration: Slack | Notifications, approvals, alerts | High | +| Native integration: Google Sheets | Data import/export for reporting | High | +| Templates | Lead routing, campaign workflow, data enrichment | High | +| SSO | Okta, Google Workspace | Critical for paid tier | +| Audit logging | Action tracking, compliance | High for enterprise | +| API | Custom workflow development | Medium | +| Zapier/Make | Long-tail integrations | Medium | + +## Community-Led Growth as Chasm-Crossing Strategy + +### Why Community Matters for the Chasm + +The chasm exists because pragmatists need peer references. Community is the most scalable way to create peer reference density: + +**Traditional reference strategy:** Convince 10 customers to do case studies and reference calls. Effective but doesn't scale. + +**Community reference strategy:** Create a space where hundreds of users share their experiences, ask questions, and validate each other's decisions. Every community interaction is a micro-reference. + +### Community Channels for B2B SaaS + +| Channel | Best For | Pragmatist Impact | +|---------|---------|-------------------| +| Slack/Discord community | Daily engagement, peer support | High -- organic peer validation | +| User conference | Annual flagship event | Very High -- concentrated reference exposure | +| Webinar series | Monthly education with customer speakers | High -- structured proof delivery | +| Customer advisory board | Strategic direction from top accounts | Medium -- deep relationships | +| Online forum/community site | Searchable knowledge, async discussion | Medium -- SEO + peer answers | +| User groups (regional/vertical) | Local in-person connection | High -- strongest peer trust | +| Champion program | Formalized advocacy with incentives | High -- trained references at scale | + +### Building Community for Chasm Crossing + +**Phase 1: Seed (Pre-Chasm)** +- Launch Slack/Discord community with early adopters +- Host monthly user meetups (virtual or in-person) +- Create a champion program for most active users +- Share everything openly (roadmap, decisions, challenges) + +**Phase 2: Cultivate (During Chasm Crossing)** +- Shift community content from "what's new" to "how we use it" +- Feature pragmatist success stories, not just early adopter enthusiasm +- Create segment-specific channels (e.g., #marketing-ops, #sales-ops) +- Host "customer spotlight" webinars with beachhead customers +- Encourage peer-to-peer support (pragmatists trust other pragmatists) + +**Phase 3: Scale (Post-Chasm)** +- Launch annual user conference +- Create certification program +- Establish regional user groups +- Build partner community alongside customer community +- Publish community-driven content (benchmarks, best practices) + +## Modern Metrics for Tracking Adoption Lifecycle Position + +### Dashboard: Where Are We in the Adoption Lifecycle? + +| Metric | Innovator Phase | Early Adopter Phase | Chasm | Early Majority Phase | +|--------|----------------|--------------------|---------|--------------------| +| User growth source | Organic, tech communities | Founder network, events | Stalling | Peer referrals, search, analysts | +| Free-to-paid conversion | Very low (they like free) | Moderate (vision buyers) | Declining | Growing (pragmatist teams) | +| Buyer persona | Individual developers, techies | VP/Director, strategic buyer | Mixed, confused | Team lead, pragmatic manager | +| Sales cycle | Self-serve (minutes) | Weeks (founder-led) | Getting longer | Months (repeatable process) | +| Churn reason | Boredom, next shiny thing | Vision misalignment | Product gaps | Competition, whole product gaps | +| Feature requests | Cutting-edge, experimental | Custom, strategic | Fragmented | Integration, reliability, admin | +| NPS distribution | High from few, low from many | Bimodal (love/hate) | Declining overall | Stable, high from segment | + +### Key Transition Metrics + +**Signal you're approaching the chasm:** +- Early adopter revenue is plateauing +- New customers look different from existing ones +- Sales team reports longer cycles and more objections +- "Who else uses this?" becomes the top question + +**Signal you're crossing the chasm:** +- Win rate in beachhead segment is improving +- Sales cycle in beachhead is becoming predictable +- Inbound leads from beachhead segment are increasing +- Reference customers are self-generating (word of mouth) +- Retention in beachhead exceeds 90% + +**Signal you've crossed:** +- Revenue growth is accelerating without proportional sales investment +- New segments are adopting with less effort than the beachhead +- Competitors are reacting to your position +- Analysts and media recognize your category leadership +- Enterprise procurement teams are initiating contact + +## Case Studies: Modern SaaS Through the Chasm Lens + +### Slack: From IRC Replacement to Enterprise Standard + +**Beachhead:** Engineering teams at tech startups who needed a better alternative to IRC, HipChat, and email threads. + +**Chasm-crossing mechanics:** +- PLG viral loop: every message to a non-user was an invitation +- Team standardization happened naturally (you can't use Slack alone) +- Enterprise features (Enterprise Grid, compliance, SSO) built specifically for pragmatist IT organizations +- Slack Connect extended the network effect across company boundaries + +**Whole product for pragmatists:** App directory (1,500+ integrations), Enterprise Grid, Workflow Builder, SSO/SCIM, message retention policies, eDiscovery compliance. + +**Where they almost got stuck:** Slack initially resisted building features for IT admins (SSO, compliance, admin controls). This delayed enterprise pragmatist adoption until approximately 2017-2018. + +### Notion: From Power-User Tool to Team Workspace + +**Beachhead:** Product and engineering teams at startups who wanted to consolidate wikis, project management, and documentation. + +**Chasm-crossing mechanics:** +- Template gallery let new users start with proven workflows instead of blank pages +- Team workspace features (permissions, shared spaces) enabled organizational adoption +- Community-created templates provided the "whole product" via user-generated content +- Notion AI features added pragmatist value (summarize, draft, organize) + +**Key chasm challenge:** Notion's flexibility was both its strength and its weakness. Pragmatists found the blank canvas overwhelming. Templates and pre-built solutions were essential to crossing. + +### Figma: Design Tool Becomes Collaboration Platform + +**Beachhead:** Product design teams at tech startups who wanted browser-based collaborative design without managing Sketch files and Abstract version control. + +**Chasm-crossing mechanics:** +- Multiplayer editing was inherently viral (invite collaborators) +- Developers used Figma for handoff (expanded beyond designers) +- FigJam expanded use case to whiteboarding and brainstorming +- Enterprise features (org-wide libraries, branching, analytics) served pragmatist design orgs + +**Whole product evolution:** Started as "Sketch in the browser." Became the whole product for design teams: design, prototyping, handoff, design systems, whiteboarding, and enterprise governance. Each addition moved Figma from designer tool to organizational design platform. + +### Linear: Issue Tracking for the Post-Jira Era + +**Beachhead:** Engineering teams at fast-growing startups (50-200 employees) frustrated with Jira's complexity. + +**Chasm-crossing mechanics:** +- Opinionated product (less configuration, more conventions) appeals to pragmatists who want structure +- Fast performance positioned against Jira's slowness -- pragmatic, measurable benefit +- Keyboard-first design appealed specifically to engineering teams +- Integration with existing developer tools (GitHub, Slack, Sentry) + +**Chasm challenge ahead:** Linear is strong with tech startups and mid-market engineering teams. Crossing to enterprise engineering organizations requires: advanced permissions, compliance features, cross-team workflows, and integrations with enterprise tools (ServiceNow, Salesforce). This is their current chasm. + +## The Modern SaaS Chasm-Crossing Playbook + +### Phase 1: Find Product-Market Fit with Innovators (Months 1-12) + +- Launch free tier or beta +- Optimize for individual user value +- Build in technical communities +- Measure: daily active users, retention, organic sign-ups + +### Phase 2: Win Early Adopters (Months 6-18) + +- Identify visionary buyers who see strategic potential +- Offer high-touch engagement for design partners +- Build team-level features +- Measure: team adoption, paid conversion, early reference quality + +### Phase 3: Define and Attack Beachhead (Months 12-24) + +- Analyze data to identify highest-value segment +- Build whole product for that segment (integrations, templates, compliance) +- Reposition from innovative to proven +- Create segment-specific content and references +- Measure: beachhead win rate, sales cycle length, beachhead retention + +### Phase 4: Dominate Beachhead (Months 18-36) + +- Build repeatable sales process for segment +- Achieve 30%+ penetration in beachhead +- Create reference engine (community, case studies, conference presence) +- Add enterprise features demanded by segment pragmatists +- Measure: market share in beachhead, inbound from segment, NPS + +### Phase 5: Expand to Adjacent Pins (Months 30-48+) + +- Score adjacent segments using bowling pin criteria +- Expand to highest-adjacency segments one at a time +- Leverage beachhead references and whole product maturity +- Measure: time to first 10 customers in new segment, reference transfer rate + +This is not a rigid timeline. Some SaaS companies cross in 18 months; others take 5 years. The sequence matters more than the speed. Skipping steps -- especially skipping beachhead dominance -- leads to the chasm. diff --git a/.agents/skills/crossing-the-chasm/references/beachhead-selection.md b/.agents/skills/crossing-the-chasm/references/beachhead-selection.md new file mode 100644 index 00000000..4a5f321b --- /dev/null +++ b/.agents/skills/crossing-the-chasm/references/beachhead-selection.md @@ -0,0 +1,278 @@ +# Beachhead Market Selection + +Choosing the right beachhead market segment is the single most consequential decision in crossing the chasm. Get it right, and you build an unassailable position from which to expand. Get it wrong, and you burn through resources chasing a market that can never become a stronghold. + +This reference provides a complete framework for identifying, evaluating, and committing to a beachhead segment. + +## Why One Segment, Not Many + +The instinct to pursue multiple segments simultaneously is the most common and most fatal mistake in chasm-crossing. Here is why focus on a single segment is non-negotiable: + +**The resource constraint:** You must build a whole product for the beachhead. Each segment requires different integrations, training, references, and positioning. Attempting two segments means delivering half a whole product to each -- and pragmatists won't buy half a solution. + +**The reference constraint:** Pragmatists buy based on peer references. "500 companies use us" means nothing. "30 orthopedic surgery centers like yours use us" means everything. References only count within a segment. + +**The word-of-mouth constraint:** Pragmatists talk to people like themselves. A win at a hospital doesn't help you sell to a bank. Concentration creates viral growth within the segment; dispersion creates silence. + +## Step 1: Brainstorm 20+ Candidate Segments + +Cast the widest possible net before narrowing. Use these prompts to generate candidates: + +### Segment Generation Prompts + +1. **By industry vertical:** Which industries have the problem you solve? List every one. +2. **By company size:** Within each industry, which company size tier feels the pain most? +3. **By job function:** Which roles are most affected by the problem? +4. **By use case:** What specific workflow or process does your product improve? +5. **By geography:** Are there regions where the problem is more acute? +6. **By technology stack:** Who uses complementary technology that creates an opportunity? +7. **By regulatory environment:** Are there compliance mandates that create urgency? +8. **By existing behavior:** Who is already solving this with painful workarounds? + +### Example: B2B Data Analytics Platform + +| # | Candidate Segment | +|---|-------------------| +| 1 | Financial services risk teams (50-500 employees) | +| 2 | Healthcare claims processing departments | +| 3 | E-commerce merchandising teams | +| 4 | SaaS product analytics teams | +| 5 | Manufacturing quality control departments | +| 6 | Retail supply chain planners | +| 7 | Insurance underwriting teams | +| 8 | Government data reporting offices | +| 9 | Pharmaceutical clinical trial analysts | +| 10 | Real estate portfolio analysts | +| 11 | Media ad-tech operations teams | +| 12 | Logistics fleet optimization teams | +| 13 | Telecom network planning teams | +| 14 | University research departments | +| 15 | Nonprofit donor analytics teams | +| 16 | Agricultural yield optimization teams | +| 17 | Energy grid management teams | +| 18 | Construction project estimation teams | +| 19 | Legal discovery and compliance teams | +| 20 | HR people analytics teams | +| 21 | Marketing attribution teams at DTC brands | +| 22 | Cybersecurity threat intelligence teams | + +**Rule of thumb:** If you can't generate 20 candidates, you don't understand your market well enough yet. Talk to more customers and prospects before proceeding. + +## Step 2: Score Each Segment + +### Scoring Criteria + +Rate each segment on a 1-5 scale for each criterion: + +#### Criterion 1: Target Customer Pain (Weight: High) + +How urgent and expensive is the problem for this segment? + +| Score | Description | +|-------|-------------| +| 1 | Nice-to-have; no budget allocated for this problem | +| 2 | Recognized problem but low priority | +| 3 | Known pain point with some budget; competes with other priorities | +| 4 | Significant pain causing measurable losses; active solution search | +| 5 | Hair-on-fire problem; the segment is desperate for a solution now | + +#### Criterion 2: Whole Product Feasibility (Weight: High) + +Can you deliver a complete solution for this segment within 6-12 months? + +| Score | Description | +|-------|-------------| +| 1 | Massive gaps; would take 2+ years and many partnerships | +| 2 | Major gaps in several areas; unclear how to fill them | +| 3 | Moderate gaps; achievable with 2-3 key partnerships | +| 4 | Small gaps; one partnership or one quarter of development fills them | +| 5 | Your current product, with minor additions, is already the whole product | + +#### Criterion 3: Segment Accessibility (Weight: Medium) + +Can you reach and engage decision-makers in this segment? + +| Score | Description | +|-------|-------------| +| 1 | No channels, no connections, no presence | +| 2 | Weak access; would require significant investment to reach | +| 3 | Some access through one channel (e.g., one conference, one publication) | +| 4 | Good access through multiple channels; some existing relationships | +| 5 | Strong existing relationships; team members from this industry; clear channels | + +#### Criterion 4: Competitive Landscape (Weight: Medium) + +How strong is existing competition in this segment? + +| Score | Description | +|-------|-------------| +| 1 | Dominant incumbent with deep entrenchment and switching costs | +| 2 | Strong competitor with established position | +| 3 | Competitors exist but none dominant; fragmented market | +| 4 | Weak or distracted competitors; segment underserved | +| 5 | No direct competition; segment uses manual workarounds | + +#### Criterion 5: Word-of-Mouth Potential (Weight: High) + +Do members of this segment communicate with each other frequently? + +| Score | Description | +|-------|-------------| +| 1 | Isolated; no community, no shared channels | +| 2 | Minimal interaction; occasional conferences | +| 3 | Moderate interaction; industry associations, periodic events | +| 4 | Strong community; active forums, frequent events, peer networks | +| 5 | Tight-knit community; everyone knows everyone; constant communication | + +#### Criterion 6: Segment Size (Weight: Medium) + +Is the segment large enough to build a business but small enough to dominate? + +| Score | Description | +|-------|-------------| +| 1 | Fewer than 20 potential customers; cannot sustain a business | +| 2 | 20-50 customers; very small but possible | +| 3 | 50-200 customers; good size for beachhead | +| 4 | 200-1,000 customers; strong beachhead with room to grow | +| 5 | 1,000-5,000 customers; large beachhead, may be difficult to dominate | + +**Note on size:** A segment of 5,000+ companies is likely too broad and should be subdivided. A score of 5 can actually be a warning sign. + +## Segment Evaluation Scorecard Template + +| Segment | Pain (x2) | Whole Product (x2) | Access (x1) | Competition (x1) | Word-of-Mouth (x2) | Size (x1) | Total (/45) | +|---------|-----------|--------------------|--------------|--------------------|---------------------|------------|-------------| +| Financial risk teams | 4 (8) | 3 (6) | 4 (4) | 3 (3) | 3 (6) | 4 (4) | 31 | +| SaaS product analytics | 5 (10) | 5 (10) | 5 (5) | 2 (2) | 5 (10) | 4 (4) | 41 | +| Healthcare claims | 4 (8) | 2 (4) | 2 (2) | 4 (4) | 3 (6) | 3 (3) | 27 | +| *[Your segment]* | | | | | | | | + +**Interpretation:** +- 35-45: Strong beachhead candidate -- investigate further +- 25-34: Possible but has significant weaknesses to address +- Below 25: Likely not a viable beachhead + +## Step 3: Deep-Dive the Top 3 Candidates + +For the top 3 scoring segments, conduct deeper validation: + +### Validation Checklist + +- [ ] **Talk to 5+ potential customers** in the segment. Do they confirm the pain? Would they pay? +- [ ] **Map the whole product.** What exactly is needed beyond your core product? Who could partner? +- [ ] **Identify existing references.** Do you already have any customers in this segment? +- [ ] **Test messaging.** Does the positioning statement resonate when you say it out loud? +- [ ] **Assess team fit.** Does your team have domain knowledge? Credibility? +- [ ] **Model the economics.** What is the realistic deal size? How many deals to reach $X revenue? +- [ ] **Map the competition.** What will incumbents do when you enter? + +## Step 4: Choose ONE and Commit + +After scoring and validation, select a single segment. This is not a reversible decision made lightly -- it is a strategic commitment that shapes your product, hiring, partnerships, and messaging for the next 12-24 months. + +### Commitment Checklist + +- [ ] The entire leadership team agrees on the beachhead +- [ ] Product roadmap is adjusted to serve this segment's whole product needs +- [ ] Marketing messaging is rewritten for this segment +- [ ] Sales team is trained on this segment's buying process +- [ ] Partnership conversations are initiated for whole product gaps +- [ ] Success metrics are defined for segment dominance + +## Common Beachhead Mistakes + +### Mistake 1: Too Broad + +**Example:** "Our beachhead is healthcare." + +Healthcare includes hospitals, clinics, pharma companies, insurance companies, medical device makers, and dozens of other sub-segments. Each has different buyers, different pain points, different procurement processes, and different competitive landscapes. + +**Fix:** "Our beachhead is radiology departments at community hospitals with 100-300 beds in the US Midwest." + +### Mistake 2: Too Narrow + +**Example:** "Our beachhead is left-handed orthodontists in Portland, Oregon." + +A segment of 12 potential customers cannot sustain a business or generate meaningful word-of-mouth. + +**Fix:** Expand to a segment with 50-1,000 potential customers that still has tight internal communication networks. + +### Mistake 3: Multiple Beachheads + +**Example:** "We're targeting both fintech startups and healthcare enterprises." + +These segments have nothing in common. Different buyers, different sales cycles, different integrations, different compliance requirements. You'll build half a whole product for each and dominate neither. + +**Fix:** Choose the one with the higher score. Return to the other after dominating the first. + +### Mistake 4: Choosing Based on Size Alone + +**Example:** "The enterprise HR market is $50B, so that's our beachhead." + +Large markets have entrenched incumbents. You cannot dominate a $50B market as a startup. You need a segment small enough to own. + +**Fix:** Find the underserved niche within the large market. + +### Mistake 5: Choosing Based on Existing Customers + +**Example:** "We have three enterprise customers in three different industries, so we'll target all three." + +Existing customers in different segments do not constitute a beachhead. They are early adopters who bought for different reasons. + +**Fix:** Evaluate which of those industries has the best beachhead characteristics, and focus there. + +## Examples: Good vs Bad Beachhead Choices + +### Salesforce (Good) + +- **Bad choice:** CRM for all businesses +- **Good choice (actual):** Sales force automation for inside sales teams at B2B tech companies in Silicon Valley +- **Why it worked:** Tight community (everyone knows each other), urgent pain (managing growing sales pipelines), accessible (Salesforce founders were embedded in this community), weak competition (Siebel was too complex and expensive), strong word-of-mouth (sales leaders move between startups) + +### Slack (Good) + +- **Bad choice:** Team communication for all companies +- **Good choice (actual):** Internal messaging for engineering teams at tech startups +- **Why it worked:** Engineers talk to each other constantly (conferences, GitHub, Twitter), startup teams adopt tools bottom-up, engineering teams have the most acute IRC/email pain, viral expansion from team to team + +### Segway (Bad) + +- **Attempted beachhead:** Everyone who walks +- **Problem:** No specific segment with urgent pain. Tourists don't have urgent transportation pain. Commuters have infrastructure constraints. Law enforcement has procurement cycles. No segment was concentrated enough to dominate. +- **Result:** Stuck in the chasm permanently. + +## Scenarios Worksheet + +### Scenario A: Enterprise SaaS with 5 Early Adopter Customers + +Your 5 early adopter customers are in: financial services (2), healthcare (1), retail (1), and manufacturing (1). + +**Do not** try to serve all four industries. Evaluate which has the best beachhead characteristics. Financial services has two customers (more references), but check: Are they similar companies? Is the word-of-mouth network strong? Can you build the whole product? + +### Scenario B: Developer Tool with Strong Open Source Adoption + +You have 10,000 developers using the free version. Only 50 are paying. + +**Do not** try to convert all 10,000. Find the segment within those 10,000 where the pain is most acute and the willingness to pay is highest. Which teams are using the tool most intensively? What do they have in common? That commonality is your beachhead. + +### Scenario C: Horizontal Platform (Analytics, AI, Communication) + +Your platform could serve any industry. The temptation to stay horizontal is overwhelming. + +**Resist it.** Pick the vertical where you have the most unfair advantage: existing relationships, domain expertise on your team, strongest early adopter success, or weakest competition. Go deep. You can go broad later. + +### Scenario D: Marketplace or Network-Effect Business + +You need both sides of the market. Pick the beachhead for the supply side first (they're harder to attract), in the geography or vertical where you can achieve the highest density fastest. + +## From Beachhead to Expansion + +Once you dominate your beachhead (see: expansion.md), the bowling pin strategy takes over. But "domination" means: + +- 30-50%+ market share within the segment +- Strong reference base (10+ vocal advocates) +- Repeatable sales process with predictable metrics +- Whole product fully assembled +- Competition acknowledges your leadership in this niche + +Until you hit these markers, you have not earned the right to expand. Expanding prematurely from an unconquered beachhead is the second most common chasm-crossing failure. diff --git a/.agents/skills/crossing-the-chasm/references/buyer-segments.md b/.agents/skills/crossing-the-chasm/references/buyer-segments.md new file mode 100644 index 00000000..90a77407 --- /dev/null +++ b/.agents/skills/crossing-the-chasm/references/buyer-segments.md @@ -0,0 +1,299 @@ +# Buyer Segments in the Technology Adoption Lifecycle + +Understanding buyer psychology is the single most important factor in technology marketing. Each segment in the adoption lifecycle has distinct motivations, fears, decision processes, and communication preferences. Treating them as a homogeneous market is the primary reason technology products stall. + +This reference provides deep psychographic profiles for each buyer type, practical identification methods, and messaging frameworks tailored to each segment. + +## Innovators (Technology Enthusiasts) -- 2.5% of Market + +### Psychographic Profile + +Innovators pursue new technology as a central interest in their lives, regardless of its immediate practical application. They are the gatekeepers to the rest of the lifecycle: if they reject your product, it never gets to anyone else. + +**Core motivations:** +- Fascination with technology for its own sake +- Desire to explore new capabilities before anyone else +- Identity tied to being on the bleeding edge +- Joy in tinkering, breaking, and rebuilding + +**How they discover products:** +- Hacker News, Reddit, niche forums, GitHub +- Technical conferences and meetups +- Direct outreach from founders (they love early access) +- Open source communities and Discord servers + +**Decision process:** +- Evaluate based on technical architecture, not business value +- Will tolerate bugs, missing features, and poor documentation +- Buy quickly -- often within hours of discovery +- Price insensitive for new technology (but expect free tiers or open source options) + +### Messaging for Innovators + +| Do | Do Not | +|----|--------| +| Lead with technical architecture | Lead with business outcomes | +| Share the engineering blog post | Share the glossy landing page | +| Provide API docs and raw specs | Provide polished case studies | +| Invite to beta/alpha programs | Wait for GA to engage them | +| Be transparent about limitations | Oversell maturity | + +**Example messaging:** "We built a new vector database engine using a novel indexing algorithm that achieves 10x throughput on high-dimensional embeddings. Here's the technical whitepaper and the open source benchmark suite." + +### Value of Innovators + +- Provide early technical validation and bug reports +- Generate word-of-mouth in technical communities +- Serve as a reality check on your architecture +- Will NOT provide business references for later segments + +## Early Adopters (Visionaries) -- 13.5% of Market + +### Psychographic Profile + +Early adopters are strategic buyers who see technology as a means to achieve a dramatic competitive advantage. They are not technologists -- they are business leaders with imagination and willingness to take calculated risks. + +**Core motivations:** +- Desire for order-of-magnitude improvement (10x, not 10%) +- Vision of transforming their organization or industry +- Willingness to bet on unproven solutions for strategic gain +- Personal career ambition tied to being a change agent + +**Typical titles:** +- VP or C-level with a transformation mandate +- Founder/CEO of a fast-growing company +- Head of Innovation or Digital Transformation +- Business unit leaders under pressure to reinvent + +**How they buy:** +- Top-down decision: executive sponsors the project +- Fast procurement cycles (weeks, not months) +- Willing to fund custom development and pilots +- Budget comes from strategic/innovation funds, not operational budgets + +**Decision process:** +- Evaluate based on vision alignment and potential impact +- Tolerate incomplete products if the vision is compelling +- Want direct access to company founders and leadership +- Expect customization and high-touch engagement + +### Messaging for Early Adopters + +| Do | Do Not | +|----|--------| +| Paint a bold vision of the future | Talk about incremental improvements | +| Show strategic differentiation potential | Show feature comparison matrices | +| Provide executive-level engagement | Route them through standard sales | +| Offer co-development partnerships | Offer off-the-shelf solutions only | +| Frame as competitive weapon | Frame as productivity tool | + +**Example messaging:** "Companies using our platform are fundamentally reimagining how they approach customer intelligence. We're working with three category leaders to define the next generation of predictive analytics. We'd like to explore a strategic partnership." + +### The Danger of Early Adopters + +Early adopters provide intoxicating validation. They buy fast, pay well, and say wonderful things. But they are dangerous: + +- Their testimonials scare pragmatists ("too visionary") +- They demand customization that fragments your product +- They set unrealistic expectations for mainstream buyers +- Success with them creates false confidence about product-market fit + +## The Chasm + +The gap between early adopters and early majority is not just a marketing problem -- it is a fundamental disconnect in buyer psychology. Pragmatists do not trust visionaries. References from early adopters are worse than no references at all. + +### Why the Chasm Exists + +| Factor | Early Adopter View | Early Majority View | +|--------|-------------------|---------------------| +| Risk | Acceptable for strategic gain | Must be minimized | +| References | Not needed | Essential -- from peers | +| Product completeness | Partial is fine | Must be whole product | +| Vendor relationship | Strategic partner | Reliable supplier | +| Innovation | Core value | Potential threat | +| Buying motive | Get ahead | Don't fall behind | + +## Early Majority (Pragmatists) -- 34% of Market + +### Psychographic Profile + +Pragmatists are the largest segment and the key to market dominance. They are practical, risk-averse, and make decisions by consensus. They want proven solutions that make their existing processes better without disruption. + +**Core motivations:** +- Improve productivity and efficiency incrementally +- Reduce risk in their operations +- Follow proven best practices +- Stay competitive without taking unnecessary chances + +**How they buy:** +- Committee-based decisions with multiple stakeholders +- Long evaluation cycles (months, sometimes quarters) +- Heavy reliance on peer references and analyst reports +- Structured RFP processes and vendor comparisons +- Require proof of ROI before purchase + +**What they need before buying:** +- References from companies similar to theirs (same size, same industry) +- A complete solution, not a toolkit requiring assembly +- Clear implementation plan with defined milestones +- Vendor stability and long-term viability evidence +- Integration with their existing technology stack +- Support, training, and professional services + +### Messaging for Pragmatists + +| Do | Do Not | +|----|--------| +| Lead with peer references and case studies | Lead with vision or innovation | +| Quantify ROI with specific metrics | Use vague value propositions | +| Emphasize completeness and ease of adoption | Emphasize flexibility and customization | +| Show industry analyst validation | Show press coverage of the technology | +| Offer pilot programs with clear success criteria | Ask for a leap of faith | +| Use "proven," "reliable," "trusted" | Use "revolutionary," "disruptive," "first" | + +**Example messaging:** "Over 200 mid-market manufacturers use our platform to reduce inventory costs by an average of 23%. Here's a case study from Acme Manufacturing, a company similar to yours, showing their 14-month implementation and measured results." + +### Identifying Pragmatists in Your Pipeline + +Checklist of pragmatist behaviors: +- [ ] Asks "Who else in our industry uses this?" +- [ ] Wants to speak with reference customers +- [ ] Involves multiple stakeholders in evaluation +- [ ] Asks about integration with existing systems +- [ ] Requests detailed implementation timelines +- [ ] Inquires about vendor financial stability +- [ ] Compares you against established alternatives +- [ ] Asks about support SLAs and escalation paths + +## Late Majority (Conservatives) -- 34% of Market + +### Psychographic Profile + +Conservatives buy technology only when it becomes an established standard. They are uncomfortable with technology and want it to be invisible -- embedded in a solution they already understand. + +**Core motivations:** +- Avoid being disadvantaged by not adopting +- Minimize cost and complexity +- Stick with trusted vendors and known brands +- Avoid change unless absolutely necessary + +**How they buy:** +- Buy from established vendors they already work with +- Choose the market leader by default +- Prefer bundled solutions over point products +- Extremely price sensitive +- Want pre-configured, turnkey solutions + +### Messaging for Conservatives + +| Do | Do Not | +|----|--------| +| Emphasize simplicity and low maintenance | Highlight features or configurability | +| Bundle with products they already use | Sell as standalone | +| Position as industry standard | Position as innovative | +| Offer fixed, predictable pricing | Offer usage-based or complex pricing | +| Provide white-glove onboarding | Assume self-service capability | + +**Example messaging:** "Our solution is now included in the Microsoft 365 suite you already use. It's pre-configured for your industry and requires no additional IT setup." + +## Laggards (Skeptics) -- 16% of Market + +### Psychographic Profile + +Laggards actively resist technology adoption. They buy only when the old way is no longer available or when regulatory requirements force adoption. They are not a target market -- they are a compliance segment. + +**How they end up buying:** +- Regulation mandates the technology +- Their existing solution is discontinued +- Business processes make non-adoption impossible +- The technology becomes so embedded it's invisible + +**Messaging approach:** Don't market to laggards. They come to you when they have no choice. Ensure your product supports their forced adoption with minimal friction. + +## Cross-Segment Comparison + +### Buying Criteria by Segment + +| Criteria | Innovators | Early Adopters | Early Majority | Late Majority | Laggards | +|----------|-----------|----------------|----------------|---------------|----------| +| **Primary driver** | Technology | Vision | Productivity | Necessity | Compliance | +| **Risk tolerance** | Very high | High | Low | Very low | None | +| **Price sensitivity** | Low | Low | Medium | High | Very high | +| **References needed** | None | Few | Many, from peers | Market standard | N/A | +| **Decision speed** | Hours/days | Weeks | Months | Quarters | When forced | +| **Decision maker** | Individual | Executive | Committee | Procurement | Policy | +| **Product completeness** | Alpha is fine | Beta is fine | Must be whole product | Must be commodity | Must be invisible | + +### Communication Channels by Segment + +| Segment | Primary Channels | Content Type | +|---------|-----------------|--------------| +| Innovators | Hacker News, GitHub, tech blogs, Discord | Technical deep dives, benchmarks, architecture docs | +| Early Adopters | Executive events, board networks, industry conferences | Vision decks, strategic briefings, executive roundtables | +| Early Majority | Industry analysts, peer networks, trade publications | Case studies, ROI reports, comparison guides | +| Late Majority | Existing vendor channels, IT consultants | Bundled offerings, turnkey packages | +| Laggards | Regulatory communications, mandatory upgrades | Compliance documentation, migration guides | + +## Identifying Your Current Customer Segment + +### Diagnostic Questions + +Ask yourself these questions about your current customer base: + +1. **Why did your last 10 customers buy?** + - "It looked cool/interesting" = Innovators + - "It could transform our business" = Early Adopters + - "Our competitor uses it and it works" = Early Majority + - "We had to because everyone else does" = Late Majority + +2. **How long was the sales cycle?** + - Under 2 weeks = Innovators or Early Adopters + - 1-3 months = Transitioning to Early Majority + - 3-12 months = Early Majority + - Over 12 months = Late Majority + +3. **What did customers ask about most during evaluation?** + - Technical specs and architecture = Innovators + - Strategic vision and roadmap = Early Adopters + - References, integrations, and support = Early Majority + - Price, bundling, and vendor stability = Late Majority + +### Warning Signs You're Selling to the Wrong Segment + +**Signs you're stuck with innovators when you need early adopters:** +- Lots of free/trial users, very few paid +- Users love the tech but can't articulate business value +- Engagement is deep but revenue is shallow +- Community is active but enterprise deals stall + +**Signs you're stuck with early adopters when you need early majority:** +- A few large deals but can't replicate them +- Every customer wants something different +- Revenue is lumpy and unpredictable +- Customers love your vision but prospects ask "Who else uses this?" +- High NPS from existing customers but low conversion of pragmatist prospects + +**Signs you're accidentally selling to late majority when you should be targeting early majority:** +- Extreme price pressure on every deal +- Customers want zero risk and zero change +- Competitors are well-established in accounts +- Deals only close when bundled with other products + +## Segment Migration Strategy + +As you cross the chasm, your entire go-to-market must shift: + +### What Changes When Moving from Early Adopters to Early Majority + +| Dimension | Early Adopter Approach | Early Majority Approach | +|-----------|----------------------|------------------------| +| Sales motion | Founder/CEO-led | Repeatable, team-based | +| Product | Flexible platform | Complete solution | +| Pricing | Custom, value-based | Standardized, transparent | +| Marketing | Vision and thought leadership | Proof and social validation | +| Support | High-touch, ad hoc | Structured, scalable | +| Success metric | Logos and vision alignment | Revenue predictability and retention | +| Content | Keynotes and manifestos | Case studies and ROI calculators | +| Partnerships | None needed | Essential for whole product | + +This shift is the essence of crossing the chasm. Companies that attempt to serve both segments simultaneously with the same go-to-market will fail at both. diff --git a/.agents/skills/crossing-the-chasm/references/case-studies.md b/.agents/skills/crossing-the-chasm/references/case-studies.md new file mode 100644 index 00000000..c119c233 --- /dev/null +++ b/.agents/skills/crossing-the-chasm/references/case-studies.md @@ -0,0 +1,390 @@ +# Crossing the Chasm: Case Studies + +Theory matters, but pattern recognition from real companies is what makes the framework actionable. This reference provides detailed case studies of companies that successfully crossed the chasm, companies that failed, and the cross-cutting patterns that distinguish success from failure. + +Each case study follows the same structure: Company and Product, Early Adopter Success, The Chasm Challenge, Strategy Used, Outcome, and Key Lessons. + + +## Table of Contents +1. [Case Study 1: Salesforce -- CRM Becomes Cloud Computing Standard](#case-study-1-salesforce-crm-becomes-cloud-computing-standard) +2. [Case Study 2: Documentum -- Content Management Crosses Through Vertical Focus](#case-study-2-documentum-content-management-crosses-through-vertical-focus) +3. [Case Study 3: VMware -- Virtualization Goes Mainstream](#case-study-3-vmware-virtualization-goes-mainstream) +4. [Case Study 4: Palm -- The PDA That Couldn't Cross](#case-study-4-palm-the-pda-that-couldnt-cross) +5. [Case Study 5: Segway -- Stuck in the Chasm Permanently](#case-study-5-segway-stuck-in-the-chasm-permanently) +6. [Case Study 6: Zoom -- Video Conferencing Crosses Before the Pandemic](#case-study-6-zoom-video-conferencing-crosses-before-the-pandemic) +7. [Case Study 7: Atlassian -- Developer Tools to Enterprise Platform](#case-study-7-atlassian-developer-tools-to-enterprise-platform) +8. [Cross-Cutting Patterns of Successful Chasm Crossings](#cross-cutting-patterns-of-successful-chasm-crossings) +9. [Warning Signs of Being Stuck in the Chasm](#warning-signs-of-being-stuck-in-the-chasm) + +--- + +## Case Study 1: Salesforce -- CRM Becomes Cloud Computing Standard + +### Company and Product + +Salesforce launched in 1999 as a cloud-based sales force automation tool, founded by Marc Benioff after leaving Oracle. The core product was a web-based CRM that required no on-premise installation. + +### Early Adopter Success + +Early adopters were tech-savvy sales leaders at Silicon Valley startups who hated Siebel and ACT! for their complexity and IT overhead. They loved Salesforce because: +- No software to install or maintain +- Accessible from anywhere +- Fast setup (days, not months) +- Pay-as-you-go pricing + +By 2002, Salesforce had several thousand customers, almost entirely technology companies with small sales teams. + +### The Chasm Challenge + +Pragmatist sales leaders at mid-market and enterprise companies were skeptical: +- "Cloud" was unproven for business-critical data +- Security concerns about storing customer data off-premise +- Limited integrations with existing enterprise systems +- No offline access (internet reliability was inconsistent) +- Lacked reporting sophistication of enterprise CRM +- No reference customers in their industry + +### Strategy Used + +**Beachhead:** Inside sales teams at B2B technology companies (50-200 employees) + +**Whole product investments:** +- Built AppExchange marketplace (2005) to fill integration gaps through partners +- Added advanced reporting and dashboards +- Developed offline capability +- Obtained security certifications +- Created professional services for implementation +- Built an ecosystem of consulting partners + +**Positioning shift:** From "No Software" (anti-establishment, visionary) to "The #1 CRM" (proven, category leader). This shift happened gradually between 2004-2008. + +**Reference strategy:** Aggressively cultivated customer stories. Dreamforce conference (launched 2003) became the primary reference engine, growing from 1,000 attendees to 10,000+ by 2007. + +### Outcome + +Salesforce crossed the chasm by approximately 2005-2006, entering the tornado by 2008. They became the gorilla in cloud CRM with over 150,000 customers by 2010. The company reached $1B in revenue in 2009. + +### Key Lessons + +- The "No Software" positioning was perfect for early adopters but had to evolve for pragmatists +- AppExchange was the whole product strategy -- letting partners fill gaps faster than Salesforce could alone +- Dreamforce created a reference factory at scale +- Salesforce stayed focused on CRM for years before expanding to adjacent categories + +## Case Study 2: Documentum -- Content Management Crosses Through Vertical Focus + +### Company and Product + +Documentum (founded 1990) built enterprise content management software for managing large volumes of documents with version control, workflows, and compliance. It was an early leader in what became "enterprise content management" (ECM). + +### Early Adopter Success + +Pharmaceutical companies and financial services firms were early adopters. They had massive document management challenges (regulatory filings, clinical trial documentation) and the technical sophistication to implement complex software. + +### The Chasm Challenge + +Mainstream enterprises found Documentum: +- Extremely complex to implement (6-12 month projects) +- Expensive (hundreds of thousands in licensing plus services) +- Required specialized system integrators +- Difficult to demonstrate ROI to non-technical buyers + +### Strategy Used + +**Beachhead:** Pharmaceutical companies managing FDA regulatory submissions + +**Why this worked:** +- FDA had strict document management requirements (compliance mandate) +- Non-compliance was catastrophic (drug approval delays) +- Pharma companies talked to each other (tight community) +- High willingness to pay (the cost of non-compliance dwarfed software costs) + +**Whole product:** Documentum built pharma-specific templates, validation packages, and compliance modules. They partnered with pharma consulting firms for implementation. + +**Positioning:** "Regulatory compliance document management" (not "enterprise content management"). Specific, pragmatist-friendly, tied to a measurable need. + +### Outcome + +Documentum dominated pharma document management, then expanded to financial services compliance, then general enterprise content management. Acquired by EMC in 2003 for $1.7B. + +### Key Lessons + +- Regulatory mandates create beachhead urgency that is impossible to ignore +- Industry-specific whole product (pharma compliance modules) was the key differentiator +- Narrow positioning ("regulatory document management") beat broad positioning ("enterprise content management") +- Partnerships with industry-specific consultancies were essential + +## Case Study 3: VMware -- Virtualization Goes Mainstream + +### Company and Product + +VMware (founded 1998) created x86 server virtualization, allowing multiple operating systems to run on a single physical server. The technology was revolutionary but initially understood only by infrastructure engineers. + +### Early Adopter Success + +Development and testing teams at technology companies were early adopters. They used VMware Workstation to run multiple operating system environments on a single developer machine. The value proposition was immediate and self-evident to technical users. + +### The Chasm Challenge + +Moving from developer desktops to production server infrastructure required convincing conservative IT operations teams: +- "Running production workloads on virtual machines? Too risky." +- Concerns about performance overhead +- No support from OS vendors (Microsoft, Red Hat) for virtualized environments +- No management tools for large-scale virtual infrastructure +- No proven disaster recovery or high availability +- IT operations teams were deeply conservative + +### Strategy Used + +**Beachhead:** Server consolidation for non-critical workloads at mid-market enterprises + +**Why this worked:** +- Mid-market companies had severe server sprawl problems (expensive, wasteful) +- Starting with non-critical workloads reduced risk perception +- ROI was immediately measurable (fewer physical servers = lower hardware and power costs) +- IT admins could try it without executive approval + +**Whole product evolution:** +- VMware ESX (2001): Bare-metal hypervisor for production servers +- VirtualCenter (2003): Centralized management for IT ops +- VMotion (2003): Live migration -- addressed the "what if a server dies?" concern +- HA and DRS (2006): Automated failover and load balancing +- Ecosystem: Storage, networking, and backup partners certified for VMware + +**Positioning shift:** From "run multiple OS on one machine" (technology description) to "reduce server costs by 60% and improve disaster recovery" (business outcome). + +### Outcome + +VMware crossed the chasm by approximately 2005-2006 and entered the tornado by 2007-2008. The company reached $1B in revenue in 2007, just 9 years after founding. Acquired by EMC, later part of Broadcom. + +### Key Lessons + +- Starting with non-critical workloads was a brilliant risk-reduction strategy for pragmatists +- Each whole product addition (VMotion, HA) specifically addressed a pragmatist objection +- The shift from technology positioning to ROI positioning was critical +- Bottom-up adoption by IT admins created demand that executives then approved + +## Case Study 4: Palm -- The PDA That Couldn't Cross + +### Company and Product + +Palm launched the PalmPilot in 1996, a handheld personal digital assistant. It was a massive early adopter success, with intuitive design and practical functionality (calendar, contacts, notes, tasks). + +### Early Adopter Success + +Technology enthusiasts and business executives loved the PalmPilot: +- Sold 1 million units in its first 18 months +- Created the PDA category +- Strong developer community building applications +- Graffiti handwriting recognition was an enthusiast favorite + +### The Chasm Challenge + +Palm needed to cross from tech enthusiasts and visionary executives to mainstream business users. The challenges: +- No email integration (Blackberry solved this) +- No always-on connectivity +- Limited enterprise IT management capabilities +- Syncing was unreliable and required desktop cradle +- No enterprise security features +- IT departments couldn't manage or secure Palm devices + +### What Went Wrong + +**Failed beachhead definition:** Palm tried to be "a handheld computer for everyone" instead of picking a specific segment and building the whole product for it. + +**Whole product gaps:** +- No push email (Blackberry delivered this) +- No enterprise device management +- No cellular data connectivity (until too late) +- No server-side integration with enterprise systems +- Developer platform fragmented across Palm OS versions + +**Competitive failure:** Blackberry targeted a specific beachhead (email-dependent executives at enterprises) and built the complete whole product: push email, enterprise server integration, IT management tools, carrier partnerships for data connectivity. + +### Outcome + +Palm's market share declined from the early 2000s onward. Blackberry crossed the chasm where Palm could not, dominating enterprise mobile until the smartphone era. Palm was eventually acquired by HP in 2010 and shut down. + +### Key Lessons + +- Having the first-mover product advantage means nothing without a whole product for pragmatists +- Blackberry won by choosing a narrower, more specific beachhead with a complete solution +- Palm's attempt to serve everyone meant they served no pragmatist segment well +- The feature that delighted enthusiasts (Graffiti) was irrelevant to mainstream buyers + +## Case Study 5: Segway -- Stuck in the Chasm Permanently + +### Company and Product + +Segway launched in 2001 with enormous pre-launch hype. The self-balancing personal transporter was positioned as a revolution in urban transportation. + +### Early Adopter Success (Limited) + +Technology enthusiasts were fascinated. Media coverage was massive. Steve Jobs reportedly said it was "as big a deal as the PC." Venture capitalist John Doerr predicted it would reach $1B in revenue faster than any company in history. + +### The Chasm Challenge + +Everything about the Segway violated chasm-crossing principles: + +**No beachhead segment:** Who exactly was this for? Commuters? Tourists? Warehouse workers? Police? There was no segment with urgent, expensive pain that the Segway uniquely solved. + +**No whole product:** The Segway was a standalone device with no supporting infrastructure -- no charging stations, no storage facilities, no maintenance network, no insurance framework, no clear legal status for sidewalks and roads. + +**Wrong positioning:** "Revolution in transportation" terrified pragmatists. There was no category to anchor to. Was it a bicycle? A car? A scooter? Pragmatists couldn't categorize it. + +**No reference customers:** Who would a pragmatist call to validate this purchase? There were no peer references because there were no defined peers. + +**Infrastructure dependencies:** The Segway needed sidewalks wide enough, buildings with storage, and cities with regulations accommodating it. None of this existed. + +### Outcome + +Segway sold approximately 140,000 units in its first 7 years -- far below the 50,000 per month originally projected. The company was acquired by Ninebot in 2015 for a fraction of its invested capital. The original Segway PT was discontinued in 2020. + +### Key Lessons + +- Massive hype from innovators and media does not predict mainstream adoption +- Without a specific segment experiencing specific pain, there is no beachhead +- "Revolutionary" products without a clear category are nearly impossible to position for pragmatists +- Infrastructure dependencies multiply the whole product gap exponentially +- Segway eventually found niche beachheads (warehouse tours, security patrols) but never crossed to mainstream + +## Case Study 6: Zoom -- Video Conferencing Crosses Before the Pandemic + +### Company and Product + +Zoom Video Communications launched in 2013 in a market already crowded with WebEx, GoToMeeting, Skype, and Google Hangouts. Founded by Eric Yuan, a former WebEx engineering VP who believed video conferencing could be dramatically simpler and more reliable. + +### Early Adopter Success + +Technology companies and startups adopted Zoom quickly because: +- Dramatically better video and audio quality than incumbents +- One-click join (no downloads, no plugins for attendees) +- Free tier with generous limits +- Simple, intuitive interface + +### The Chasm Challenge + +Enterprise pragmatists were loyal to existing solutions: +- WebEx was the default for many large companies +- Microsoft was bundling Skype for Business (later Teams) with Office 365 +- IT departments had standardized on existing solutions +- Switching costs were perceived as high (training, integrations, contracts) + +### Strategy Used + +**Beachhead:** Small and mid-market companies where individuals could adopt without IT approval + +**Key tactics:** +- Freemium model let individuals start without procurement +- Bottom-up adoption: one person uses it, invites others, it spreads +- Every meeting was a demo (attendees experienced the product quality) +- Focused on reliability and simplicity above all +- Built integrations with Slack, Salesforce, Google Calendar, Outlook +- Added enterprise features (SSO, admin controls, recording) for IT buy-in +- Aggressive case study and ROI content program + +**Positioning:** "Video conferencing that just works." Not revolutionary, not disruptive -- simply better at the thing you already do. + +### Outcome + +Zoom crossed the chasm by approximately 2018-2019, pre-pandemic. Revenue grew from $60M (2017) to $330M (2019) to $622M (FY2020, pre-pandemic). The pandemic then created a tornado that catapulted Zoom to $4B+ in revenue. + +### Key Lessons + +- "Just works" is the ultimate pragmatist positioning +- Every meeting was a built-in demo -- the product marketed itself +- Freemium enabled bottom-up adoption that bypassed conservative IT gatekeepers +- The pandemic tornado was luck, but Zoom had already crossed the chasm and was positioned to capture it + +## Case Study 7: Atlassian -- Developer Tools to Enterprise Platform + +### Company and Product + +Atlassian (founded 2002 in Australia) launched Jira as a bug tracking tool for software development teams. The company grew to include Confluence (wiki), Bitbucket (code hosting), and eventually a full suite of collaboration tools. + +### Early Adopter Success + +Small development teams at tech companies adopted Jira for its flexibility and low cost. Atlassian's no-sales-team model (entirely self-service) meant developers could adopt without procurement approval. + +### The Chasm Challenge + +Expanding from developer teams to broader enterprise adoption required: +- Non-technical users finding Jira usable (historically complex UI) +- IT and project management teams adopting alongside developers +- Enterprise compliance, security, and administration features +- Competing with entrenched tools (Microsoft Project, ServiceNow, BMC) + +### Strategy Used + +**Beachhead:** Software development teams at technology companies (agile project tracking) + +**Expansion path:** +- Pin 1: Dev teams at tech startups (Jira for bug tracking) +- Pin 2: Dev teams at mid-market tech (Jira + Confluence) +- Pin 3: IT service management teams (Jira Service Management) +- Pin 4: Business teams (Trello acquisition, Jira Work Management) +- Pin 5: Enterprise-wide collaboration (Atlassian Cloud, unified platform) + +**Key decisions:** +- Acquired Trello (2017) for mainstream, non-technical users +- Built Atlassian Cloud to satisfy enterprise IT requirements +- Created marketplace for partner integrations (whole product) +- Maintained self-service model even at enterprise scale + +### Outcome + +Atlassian crossed the chasm in the developer tools segment by approximately 2010-2012. The broader enterprise platform crossing began around 2017 with the Trello acquisition and cloud migration. Revenue reached $3.5B by FY2023. + +### Key Lessons + +- Self-service / product-led growth can cross the chasm when the product is the marketing +- Each expansion was a new mini-chasm crossing with its own beachhead and whole product needs +- Acquisitions (Trello) can accelerate entry into adjacent segments +- The cloud migration was essential for enterprise pragmatists who needed centralized administration + +## Cross-Cutting Patterns of Successful Chasm Crossings + +### What Successful Companies Did + +| Pattern | Salesforce | Documentum | VMware | Zoom | Atlassian | +|---------|-----------|------------|--------|------|-----------| +| Chose specific beachhead | Inside sales at tech cos | Pharma regulatory | Non-critical servers | SMB video meetings | Dev teams at startups | +| Built whole product for segment | AppExchange ecosystem | Pharma compliance modules | VMotion, HA, mgmt tools | Integrations, admin controls | Marketplace, cloud admin | +| Shifted positioning | "No Software" to "#1 CRM" | "ECM" to "regulatory compliance" | "Virtualization" to "cut costs 60%" | "Better video" to "just works" | "Bug tracker" to "team collaboration" | +| Created reference engines | Dreamforce | Pharma conferences | ROI case studies | Every meeting = demo | Community, marketplace | +| Expanded systematically | Sales to service to marketing | Pharma to finance to general | Non-critical to production | SMB to mid-market to enterprise | Dev to IT to business teams | + +### What Failed Companies Had in Common + +| Anti-Pattern | Palm | Segway | +|-------------|------|--------| +| No specific beachhead | "Everyone" | "Everyone who walks" | +| Incomplete whole product | No push email, no enterprise mgmt | No infrastructure, no regulations | +| Revolutionary positioning | "Future of computing" | "Future of transportation" | +| No pragmatist references | Enthusiast testimonials only | Media hype, no user proof | +| Ignored infrastructure needs | Needed carrier data partnerships | Needed city infrastructure | + +## Warning Signs of Being Stuck in the Chasm + +If three or more of these are true, your company is stuck: + +- [ ] Revenue has plateaued after initial early adopter growth +- [ ] Sales cycles are getting longer, not shorter +- [ ] Most customers are still "visionary" profiles +- [ ] You cannot name your beachhead segment in one sentence +- [ ] You have customers in 5+ industries but dominate none +- [ ] Your win rate is declining even as you increase pipeline +- [ ] Pragmatist prospects ask "Who else uses this?" and you can't answer with their peers +- [ ] Your marketing still emphasizes "revolutionary" and "first" +- [ ] Every deal requires significant customization +- [ ] Your product roadmap is driven by individual customer requests, not segment needs +- [ ] You've hired multiple salespeople but only the founder can close deals +- [ ] Competitors are entering your space with more complete solutions for specific segments + +### Recovery Protocol + +1. **Stop selling broadly.** Narrow focus to the one segment with the most traction. +2. **Audit the whole product.** Interview your best customers. What's missing? +3. **Reposition.** Drop all visionary language. Lead with proof and peer references. +4. **Invest in references.** Make existing segment customers wildly successful and vocal. +5. **Say no.** Decline deals outside your beachhead until you have dominated it. diff --git a/.agents/skills/crossing-the-chasm/references/expansion.md b/.agents/skills/crossing-the-chasm/references/expansion.md new file mode 100644 index 00000000..0e4ac427 --- /dev/null +++ b/.agents/skills/crossing-the-chasm/references/expansion.md @@ -0,0 +1,278 @@ +# The Bowling Pin Strategy: Expansion After the Beachhead + +Dominating a beachhead is not the end goal -- it is the launchpad. The bowling pin strategy describes how to expand from a single conquered segment into adjacent markets, building momentum that eventually creates a tornado of mainstream adoption. + +This reference provides the complete expansion framework, adjacency evaluation criteria, timing indicators, planning templates, and real-world examples of successful (and failed) expansion paths. + +## The Bowling Pin Metaphor + +In bowling, the lead pin knocks down adjacent pins, which knock down more pins. In market expansion: + +``` + [Pin 7] [Pin 8] [Pin 9] [Pin 10] + [Pin 4] [Pin 5] [Pin 6] + [Pin 2] [Pin 3] + [Pin 1] + BEACHHEAD +``` + +- **Pin 1 (Beachhead):** The segment you dominate first +- **Pins 2-3:** Segments directly adjacent that your beachhead references influence +- **Pins 4-6:** Segments influenced by Pins 2-3 +- **Pins 7-10:** Broader market segments reached through accumulated momentum + +Each pin falls because the pins before it created references, reputation, and whole product maturity that make the next segment easier to enter. + +## Adjacency Criteria + +Not all segments are equally good expansion targets. Evaluate each potential "next pin" on three dimensions: + +### Criterion 1: Reference Credibility Transfer + +**The question:** Will our beachhead customers' success stories influence this new segment? + +| Score | Description | +|-------|-------------| +| 5 | Same industry, similar role, high mutual respect ("they're just like us") | +| 4 | Related industry or role, moderate peer recognition | +| 3 | Different industry but similar problem, some credibility | +| 2 | Tangential connection, references have limited influence | +| 1 | No connection; references from beachhead carry zero weight | + +**Example:** If your beachhead is "inside sales teams at SaaS startups," an adjacent segment of "inside sales teams at mid-market tech companies" scores a 5. "Marketing teams at SaaS startups" scores a 3. "Manufacturing plant managers" scores a 1. + +### Criterion 2: Whole Product Similarity + +**The question:** How much of our beachhead whole product transfers to this new segment? + +| Score | Description | +|-------|-------------| +| 5 | Same whole product works with no modification | +| 4 | Minor additions (one new integration, small feature) | +| 3 | Moderate additions (new integration category, content/templates) | +| 2 | Significant work (new compliance requirements, different workflows) | +| 1 | Essentially a new whole product needed | + +### Criterion 3: Incremental Sales Effort + +**The question:** Can our current sales team sell to this segment with minimal retraining? + +| Score | Description | +|-------|-------------| +| 5 | Same buyer persona, same sales process, same objections | +| 4 | Similar buyer, minor messaging changes | +| 3 | Different buyer but related domain; moderate training needed | +| 2 | Different buyer, different process, significant training | +| 1 | Completely new sales motion required | + +### Adjacency Scoring Template + +| Potential Segment | Reference Transfer (x2) | Whole Product (x2) | Sales Effort (x1) | Total (/25) | Priority | +|-------------------|------------------------|--------------------|--------------------|-------------|----------| +| | | | | | | +| | | | | | | +| | | | | | | + +**Interpretation:** +- 20-25: Immediate next pin -- expand here +- 15-19: Good candidate for pin 3-4 +- 10-14: Possible future pin, not yet +- Below 10: Not adjacent -- treat as a separate beachhead + +## Mapping Adjacent Segments from Your Beachhead + +### The Adjacency Map + +Draw your beachhead at the center and map potential expansions along four axes: + +**Axis 1: Same role, different industry** +Your buyer persona stays the same, but the industry changes. +Example: Sales ops at SaaS companies (beachhead) to sales ops at professional services firms. + +**Axis 2: Different role, same industry** +The industry stays the same, but you serve a different buyer. +Example: Sales ops at SaaS companies (beachhead) to marketing ops at SaaS companies. + +**Axis 3: Same use case, different company size** +Move up-market (enterprise) or down-market (SMB) within the same use case. +Example: Inside sales at 50-200 employee SaaS (beachhead) to inside sales at 200-1,000 employee SaaS. + +**Axis 4: Adjacent use case, same buyer** +Your buyer uses you for one workflow; expand to an adjacent workflow. +Example: Pipeline management (beachhead) to forecasting and reporting. + +### Adjacency Map Template + +``` + [Same role, different industry] + | +[Adjacent use case] --- [BEACHHEAD] --- [Different role, same industry] + | + [Same use case, different size] +``` + +For each axis, list 3-5 specific segments and score them using the adjacency criteria. + +## Expansion Planning Template + +### Expansion Roadmap + +| Phase | Timeline | Target Segment | Why Now | Key Milestone | +|-------|----------|---------------|---------|---------------| +| Phase 0 | Months 1-12 | Beachhead domination | Foundation | 30%+ market share, 10+ references | +| Phase 1 | Months 12-18 | Adjacent Pin 2 | Beachhead reference power | 5+ customers in new segment | +| Phase 2 | Months 18-24 | Adjacent Pin 3 | Pins 1+2 provide combined proof | Repeatable sales in 3 segments | +| Phase 3 | Months 24-36 | Pins 4-6 | Momentum building | Category leadership emerging | + +### Per-Segment Expansion Checklist + +Before entering a new segment, complete this checklist: + +- [ ] Beachhead segment has 30%+ market share +- [ ] At least 3 beachhead customers willing to be references for the new segment +- [ ] Whole product gap analysis completed for new segment +- [ ] Gap-filling plan with timeline (build, partner, or recommend) +- [ ] Positioning statement adapted for new segment +- [ ] At least 1 lighthouse customer in the new segment (early pragmatist) +- [ ] Sales team trained on new segment's buying process +- [ ] Marketing materials created for new segment +- [ ] Channel partners identified (if needed for new segment) +- [ ] Success metrics defined for segment entry + +## When to Expand: Domination Metrics + +Expanding before dominating the beachhead is the most common expansion mistake. Here are the signals that you've earned the right to expand. + +### Quantitative Indicators + +| Metric | Target Before Expansion | +|--------|------------------------| +| Market share in beachhead | 30-50%+ of addressable companies | +| Reference customers | 10+ vocal advocates | +| Win rate in beachhead | 40%+ against all competitors | +| Sales cycle length | Stable and predictable (not getting longer) | +| Inbound from segment | 20%+ of leads come inbound from the segment | +| Customer retention | 90%+ annual retention in beachhead | +| NPS in segment | 40+ from beachhead customers | + +### Qualitative Indicators + +- Beachhead customers proactively refer you to peers +- You are invited to speak at segment-specific events +- Industry analysts list you as a leader in the segment +- Competitors react to your beachhead position (imitation, FUD) +- New hires in the segment already know your product +- You're on the "default shortlist" for evaluations in the segment + +### Red Flags: Not Ready to Expand + +- Win rate is declining in the beachhead +- Sales cycles are getting longer, not shorter +- Customer retention is below 85% +- Reference customers are reluctant to advocate +- You haven't achieved clear thought leadership in the segment +- The sales team still relies on the founder for key deals + +## Common Expansion Mistakes + +### Mistake 1: Expanding Too Early + +**Symptom:** You have 15 customers in the beachhead and get excited about a big enterprise deal in a different segment. + +**Problem:** You divert product, sales, and marketing resources to serve a segment where you have no references, no whole product, and no positioning. The beachhead stalls, the new segment fails, and you're stuck in no-man's-land. + +**Rule:** You need dominance, not presence, in the beachhead before expanding. + +### Mistake 2: Expanding Too Far + +**Symptom:** Your beachhead is inside sales teams at SaaS startups, and your next target is procurement departments at government agencies. + +**Problem:** Zero reference transfer, completely different whole product, entirely new sales motion. This is not expansion -- it is starting over. + +**Rule:** Each new pin must score 15+ on the adjacency scorecard. + +### Mistake 3: Expanding in Too Many Directions Simultaneously + +**Symptom:** You enter three new segments at the same time because "we need to grow faster." + +**Problem:** Same as the multiple beachhead mistake, but later stage. You spread resources across segments, achieve dominance in none, and lose the momentum from the beachhead. + +**Rule:** One new segment at a time. Maximum two if they share the same whole product. + +### Mistake 4: Losing the Beachhead While Expanding + +**Symptom:** You shift attention to the new segment and a competitor enters your beachhead. + +**Problem:** Your beachhead is your foundation. If you lose it, you lose references, revenue base, and strategic position. + +**Rule:** Maintain defensive investment in the beachhead. Assign dedicated resources to protect it. + +## Real-World Expansion Paths + +### Salesforce + +| Pin | Segment | Year | Key Move | +|-----|---------|------|----------| +| 1 | Inside sales at SaaS startups | 1999-2002 | "No Software" positioning, free trials | +| 2 | Inside sales at mid-market tech | 2002-2004 | Added reporting, team management | +| 3 | All sales teams at tech companies | 2004-2006 | AppExchange launched, field sales features | +| 4 | Sales teams across all industries | 2006-2008 | Enterprise features, Gartner leadership | +| 5 | Customer service (Service Cloud) | 2009 | Adjacent use case, same buyer | +| 6 | Marketing (Marketing Cloud via acquisitions) | 2012-2014 | Adjacent role, same account | +| Tornado | Full CRM + platform for all businesses | 2015+ | Platform strategy, industry clouds | + +### HubSpot + +| Pin | Segment | Year | Key Move | +|-----|---------|------|----------| +| 1 | Inbound marketing for small B2B companies | 2006-2010 | Coined "inbound marketing," free tools | +| 2 | Marketing for mid-market B2B | 2010-2013 | Added analytics, automation, CMS | +| 3 | Sales tools for SMB (CRM) | 2014-2016 | Free CRM, adjacent use case | +| 4 | Customer service for SMB | 2017-2019 | Service Hub, full customer platform | +| 5 | All GTM teams at mid-market | 2020+ | Platform play, vertical solutions | + +### Slack + +| Pin | Segment | Year | Key Move | +|-----|---------|------|----------| +| 1 | Engineering teams at tech startups | 2013-2015 | Replaced IRC, integrated with dev tools | +| 2 | All teams at tech startups | 2015-2016 | Non-technical channels, file sharing | +| 3 | Tech teams at mid-market companies | 2016-2017 | Enterprise features, compliance, SSO | +| 4 | All knowledge workers at enterprises | 2017-2019 | Enterprise Grid, shared channels | +| 5 | External collaboration (Slack Connect) | 2020-2021 | Cross-company channels | + +## From Bowling Pins to Tornado + +The tornado phase begins when adoption accelerates beyond your direct sales efforts. Signs of the tornado: + +### Pre-Tornado Indicators + +- Multiple segments adopting simultaneously without segment-specific campaigns +- Inbound demand exceeds sales capacity +- Competitors rush to copy your approach +- Media and analysts declare you the category leader +- Customers adopt faster than you can support them + +### Strategic Shifts in the Tornado + +| Dimension | Bowling Pin Phase | Tornado Phase | +|-----------|-------------------|---------------| +| Product | Whole product per segment | Standardized platform | +| Sales | Segment-specific playbooks | Volume-based, efficient | +| Marketing | Segment references | Category leadership | +| Pricing | Value-based per segment | Standardized, scalable | +| Partnerships | Gap-filling for segments | Ecosystem building | +| Competition | Niche differentiation | Market share grab | +| Hiring | Domain experts per segment | Scalable roles | + +### The Gorilla Game + +In the tornado, the market consolidates around a leader (the gorilla). The goal of the bowling pin strategy is to enter the tornado with enough momentum, references, and market share to become the gorilla. Being a "chimp" (strong #2) or "monkey" (everyone else) in the tornado is a dramatically less valuable outcome. + +**How bowling pins create gorilla position:** +- Each dominated segment is a fortress competitors can't easily take +- Accumulated references across multiple segments create overwhelming social proof +- Whole product maturity from serving multiple segments creates platform strength +- Brand recognition from segment leadership creates category association + +The bowling pin strategy is not just about sequential growth. It is about accumulating the strategic assets that make you the inevitable choice when the tornado hits. diff --git a/.agents/skills/crossing-the-chasm/references/go-to-market.md b/.agents/skills/crossing-the-chasm/references/go-to-market.md new file mode 100644 index 00000000..7f37472c --- /dev/null +++ b/.agents/skills/crossing-the-chasm/references/go-to-market.md @@ -0,0 +1,332 @@ +# Go-to-Market Strategy for Crossing the Chasm + +The go-to-market strategy that wins early adopters will fail with pragmatists. Every element -- distribution, messaging, pricing, content, channels -- must transform when you cross the chasm. This is not an incremental shift; it is a wholesale reinvention of how you sell. + +This reference provides the complete go-to-market playbook for transitioning from early adopter sales to mainstream market penetration. + + +## Table of Contents +1. [Distribution Strategy by Adoption Segment](#distribution-strategy-by-adoption-segment) +2. [Sales Strategy Shift](#sales-strategy-shift) +3. [Marketing Message Transformation](#marketing-message-transformation) +4. [Content Marketing for Pragmatists](#content-marketing-for-pragmatists) +5. [Channel Partner Selection and Management](#channel-partner-selection-and-management) +6. [Pricing Strategy Across the Chasm](#pricing-strategy-across-the-chasm) +7. [Launch Playbook for Crossing the Chasm](#launch-playbook-for-crossing-the-chasm) +8. [Lead Generation for Pragmatist Buyers](#lead-generation-for-pragmatist-buyers) + +--- + +## Distribution Strategy by Adoption Segment + +### How Each Segment Buys + +| Segment | Discovery | Evaluation | Purchase | Implementation | +|---------|-----------|------------|----------|----------------| +| **Innovators** | Tech blogs, HN, GitHub | Try it themselves | Self-service/free | DIY | +| **Early Adopters** | Networks, conferences, thought leaders | Founder/CEO demo | Direct sales, custom deal | High-touch, co-build | +| **Early Majority** | Peers, analysts, trade publications | Committee evaluation, RFP | Channel or direct with references | Professional services | +| **Late Majority** | Existing vendor bundles | Minimal; follow the standard | Procurement process | Turnkey onboarding | + +### The Distribution Gap + +Most technology companies are structured for early adopter sales: founder-led, relationship-driven, custom deals. Crossing the chasm requires building a repeatable, scalable go-to-market engine. + +**What changes:** + +| Dimension | Early Adopter Motion | Early Majority Motion | +|-----------|---------------------|----------------------| +| Sales team | Founder/CEO + 1-2 reps | Dedicated sales team with playbooks | +| Deal size | Variable, custom | Standardized tiers | +| Sales cycle | 2-6 weeks | 2-6 months | +| Buying process | Single decision maker | Committee with procurement | +| Proposal format | Custom slide deck | Standardized proposal with ROI model | +| Proof | Demo and vision | Case studies, pilot, references | +| Contract | Flexible, negotiated | Standard terms, enterprise addendum | + +## Sales Strategy Shift + +### Phase 1: Founder-Led Sales (Pre-Chasm) + +**When:** First 10-30 customers. All early adopters or innovators. + +**Characteristics:** +- CEO/founder runs every deal +- Deep customization per customer +- Relationships drive deals +- No repeatable process +- Every deal is different + +**This works because:** Early adopters buy vision, and nobody sells the vision better than the founder. + +### Phase 2: Repeatable Sales (Crossing the Chasm) + +**When:** Targeting beachhead segment pragmatists. First 30-100 customers. + +**What must change:** +- Document the sales process and train a team +- Create standard demo scripts focused on the beachhead segment +- Build a reference library from beachhead customers +- Develop standardized pricing and packaging +- Create a qualification framework (not every lead is beachhead) + +**The beachhead sales playbook should include:** +- [ ] Ideal customer profile (ICP) for the beachhead segment +- [ ] Discovery questions specific to the segment's pain +- [ ] Standard demo flow showing the whole product +- [ ] Objection handling guide (top 10 objections and responses) +- [ ] Reference customer list with contact willingness +- [ ] ROI calculator pre-loaded with segment benchmarks +- [ ] Proposal template with case studies +- [ ] Competitive battle cards +- [ ] Implementation timeline for the segment + +### Phase 3: Channel Sales (Post-Chasm Expansion) + +**When:** Beachhead is dominated, expanding to adjacent segments. + +**Characteristics:** +- Channel partners (VARs, consultancies, MSPs) sell and implement +- Inside sales handles inbound and smaller deals +- Self-service available for lower tiers +- Standardized onboarding and implementation + +## Marketing Message Transformation + +### The Core Shift + +Early adopter marketing says: "This is new. This is different. This changes everything." + +Early majority marketing says: "This works. Others like you use it. Here are the results." + +### Message Architecture for Pragmatists + +**Level 1: Headline** +Focus on the outcome, not the technology. + +| Early Adopter Headline | Pragmatist Headline | +|------------------------|---------------------| +| "The AI revolution in sales" | "Close 30% more deals with proven sales automation" | +| "Reinvent your data stack" | "Get reports in minutes, not days" | +| "The future of customer success" | "Reduce churn by 25% like 200 SaaS companies" | + +**Level 2: Proof Points** +Pragmatists need evidence, not vision. + +- Specific metrics from reference customers ("reduced onboarding time from 6 weeks to 3 days") +- Named customers in the beachhead segment (with permission) +- Industry analyst recognition (Gartner, Forrester, G2) +- Number of customers in the segment +- Uptime and reliability statistics +- Awards and certifications + +**Level 3: Risk Reduction** +Every piece of pragmatist marketing must reduce perceived risk. + +- Free trial or pilot program +- Money-back guarantee or success-based pricing +- Clear implementation timeline +- Named customer success manager +- Published SLAs +- Visible customer support options + +## Content Marketing for Pragmatists + +### Content Types Ranked by Pragmatist Impact + +| Content Type | Impact | Why It Works | +|-------------|--------|-------------| +| **Customer case studies** | Very High | Peer proof; "someone like me succeeded" | +| **ROI calculators** | Very High | Self-serve proof of value | +| **Comparison guides** | High | Helps evaluation process | +| **Implementation guides** | High | Reduces perceived risk | +| **Industry benchmark reports** | High | Establishes thought leadership with data | +| **Webinars with customers** | Medium | Live proof, Q&A reduces concerns | +| **Best practices content** | Medium | Demonstrates expertise | +| **Technical documentation** | Medium | Reduces implementation fear | +| **Blog posts (thought leadership)** | Low | Pragmatists don't care about your vision | +| **Press releases** | Low | Pragmatists trust peers, not press | + +### Case Study Template + +Every case study for pragmatist buyers should follow this structure: + +**1. Customer Profile (1 paragraph)** +- Company name, size, industry +- Why they're relevant to the reader + +**2. Challenge (2-3 paragraphs)** +- Specific problem, quantified +- Impact on business (cost, time, risk) +- What they tried before + +**3. Solution (2-3 paragraphs)** +- Why they chose you (decision criteria) +- Implementation process (timeline, effort) +- Key features they use + +**4. Results (1-2 paragraphs with specific metrics)** +- Before/after metrics +- Quantified business impact +- Timeline to value + +**5. Quote from champion** +- Named individual with title +- Specific, credible statement + +**Target:** Create 5-10 case studies from your beachhead segment before attempting to cross the chasm. + +### ROI Calculator Framework + +Build a self-service ROI calculator for your beachhead segment: + +**Inputs (what the prospect provides):** +- Current metric (e.g., hours spent on manual reporting per week) +- Team size +- Average fully loaded employee cost +- Current tool costs (if replacing something) + +**Calculations (your model):** +- Time saved based on customer benchmarks +- Cost savings = time saved x employee cost +- Additional value (risk reduction, revenue impact) +- Net value = total savings - your product cost + +**Output:** +- Projected annual ROI +- Payback period in months +- 3-year total value + +**Credibility:** Link every assumption to a real customer's measured result. + +## Channel Partner Selection and Management + +### When to Use Channel Partners + +Channel partners become important when: +- Your beachhead segment buys through consultants or integrators +- You need local presence in geographies you don't cover +- The whole product requires implementation services you can't scale +- Pragmatist buyers trust the partner more than they trust you + +### Partner Selection Criteria + +| Criterion | Why It Matters | How to Evaluate | +|-----------|---------------|-----------------| +| Beachhead segment coverage | They must already sell to your target | Ask for customer references in the segment | +| Technical capability | They must implement your product well | Certification program and test project | +| Strategic alignment | Your product should be important to them | Revenue potential relative to their portfolio | +| Cultural fit | Shared values around customer success | Joint customer meetings, reference checks | +| Capacity | They must have bandwidth for your product | Headcount dedicated to your product line | + +### Partner Enablement Checklist + +- [ ] Sales training program (product, positioning, competitive) +- [ ] Technical certification for implementation +- [ ] Deal registration and conflict resolution process +- [ ] Joint marketing materials and co-branded content +- [ ] Partner portal with leads, deal tracking, support +- [ ] Pricing and margin structure +- [ ] Escalation paths for technical issues +- [ ] Quarterly business reviews + +## Pricing Strategy Across the Chasm + +### Pre-Chasm Pricing (Early Adopters) + +**Characteristics:** +- Value-based and negotiated per deal +- Custom scoping and SOWs +- Annual contracts with significant upfront commitment +- Discounts for vision alignment and co-development + +### Chasm-Crossing Pricing (Pragmatists) + +**Characteristics:** +- Standardized tiers (Good / Better / Best) +- Published pricing (transparency reduces risk perception) +- Monthly or annual options +- Clear feature differentiation between tiers +- Volume discounts for segment-specific needs + +**Pricing principles for pragmatists:** +1. **Make it easy to say yes:** Offer a low-commitment entry point (pilot, starter tier) +2. **Make it easy to compare:** Align your tiers with competitor pricing structures +3. **Make ROI obvious:** Price should be obviously less than the value delivered +4. **Make it predictable:** No surprise overages or hidden fees +5. **Make expansion natural:** Land with a team, expand to the organization + +### Pricing Structure Template + +| Tier | Target | Includes | Price Point Strategy | +|------|--------|----------|---------------------| +| **Starter** | Individual/small team trial | Core features, limited usage | Below competitor entry point | +| **Professional** | Beachhead segment primary | Whole product for segment, standard support | At segment willingness-to-pay | +| **Enterprise** | Large organizations in segment | Everything + SSO, SLAs, dedicated support | Premium for reduced risk and white glove | + +## Launch Playbook for Crossing the Chasm + +### Phase 1: Pre-Launch (Months 1-3) + +**Goal:** Build the arsenal before the campaign. + +- [ ] Complete whole product for beachhead segment +- [ ] Secure 3-5 reference customers with measurable results +- [ ] Write 3+ case studies +- [ ] Build ROI calculator +- [ ] Create segment-specific landing page +- [ ] Develop sales playbook and train team +- [ ] Identify and engage 2-3 channel partners +- [ ] Prepare analyst briefing materials + +### Phase 2: Soft Launch (Months 4-6) + +**Goal:** Validate positioning and go-to-market with a controlled audience. + +- [ ] Launch segment-specific landing page +- [ ] Run pilot campaign to 100 target accounts +- [ ] Host a customer webinar (reference customers present) +- [ ] Brief 2-3 industry analysts +- [ ] Test messaging with cold outreach (measure response rates) +- [ ] Refine based on feedback and results + +### Phase 3: Full Launch (Months 7-12) + +**Goal:** Achieve dominant awareness in the beachhead segment. + +- [ ] Full marketing campaign across segment channels +- [ ] Presence at segment-specific conferences and events +- [ ] Analyst report inclusion (Gartner, Forrester, G2) +- [ ] Partner co-marketing campaigns +- [ ] Content program (monthly case studies, quarterly benchmarks) +- [ ] Community building (user group, advisory board) + +## Lead Generation for Pragmatist Buyers + +### Channels Ranked by Pragmatist Effectiveness + +| Channel | Effectiveness | Notes | +|---------|-------------|-------| +| Customer referrals | Highest | Pragmatists trust peers above all | +| Industry analyst influence | Very High | Gartner/Forrester inclusion is a buying signal | +| Industry conferences/events | High | Presence validates legitimacy | +| Content marketing (case studies) | High | SEO + proof = inbound pragmatists | +| Partner referrals | High | Trusted advisor recommendations | +| Targeted outbound (ABM) | Medium | Must lead with segment-specific proof | +| Paid search (category terms) | Medium | Captures active evaluators | +| Social proof (G2, TrustRadius) | Medium | Review sites influence pragmatist research | +| Cold email/call | Low-Medium | Only works with strong segment-specific messaging | +| Brand advertising | Low | Pragmatists don't buy from ads | +| PR and press coverage | Low | Pragmatists trust peers, not journalists | + +### The Pragmatist Buyer's Journey + +| Stage | What They Do | What You Provide | +|-------|-------------|-----------------| +| **Problem recognition** | Realize current approach is unsustainable | Thought leadership on the problem (not your product) | +| **Research** | Ask peers, read analysts, search online | Case studies, comparison content, analyst presence | +| **Shortlist** | Create list of 2-4 vendors to evaluate | Clear category positioning, easy-to-find pricing | +| **Evaluate** | Demo, pilot, reference calls | Guided evaluation, reference introductions, pilot program | +| **Decide** | Committee discussion, risk assessment | Business case template, implementation plan, SLAs | +| **Implement** | Roll out to team/organization | Onboarding, training, dedicated success manager | +| **Advocate** | Tell peers about their experience | Customer advisory board, referral program, co-marketing | diff --git a/.agents/skills/crossing-the-chasm/references/positioning.md b/.agents/skills/crossing-the-chasm/references/positioning.md new file mode 100644 index 00000000..4369d9e7 --- /dev/null +++ b/.agents/skills/crossing-the-chasm/references/positioning.md @@ -0,0 +1,271 @@ +# Competitive Positioning for Crossing the Chasm + +Positioning is not what you say about your product. It is how your target customer categorizes your product in their mind relative to alternatives. When crossing the chasm, your positioning must fundamentally shift from "revolutionary new technology" to "proven solution in a category pragmatists already understand." + +This reference provides positioning frameworks, templates, testing methods, and the specific shifts required when moving from early adopter to early majority messaging. + +## The Positioning Formula + +Geoffrey Moore's positioning statement template is the gold standard for technology positioning: + +``` +For [target customer] +who [statement of the need or opportunity], +our product is a [product category] +that [statement of key benefit]. +Unlike [primary competitive alternative], +our product [statement of primary differentiation]. +``` + +Every word in this formula matters. Let's break down each element. + +### Element 1: Target Customer + +Be specific. Not "businesses" but "mid-market B2B SaaS companies with 50-200 employees." The more specific the target, the more resonant the positioning. + +**Test:** If your target customer reads this line, do they immediately say "That's me"? + +### Element 2: Need or Opportunity + +State the problem in the customer's language, not yours. This is not about your technology -- it is about their pain. + +**Bad:** "who need AI-powered data analytics" +**Good:** "who spend 20+ hours per week manually building reports from disconnected data sources" + +### Element 3: Product Category + +This is the most critical element for pragmatists. They must be able to place your product in a category they already understand. If they can't categorize it, they can't evaluate it, compare it, or budget for it. + +**Bad:** "a paradigm-shifting intelligence platform" +**Good:** "a business intelligence tool" + +### Element 4: Key Benefit + +One benefit. Not three. Not five. The single most compelling reason to buy, expressed in outcome terms. + +**Bad:** "that provides AI, ML, real-time analytics, and customizable dashboards" +**Good:** "that reduces time-to-insight from days to minutes" + +### Element 5: Competitive Alternative + +Name the thing they use today. Often this is not a direct competitor but the status quo: spreadsheets, manual processes, or an outdated legacy system. + +### Element 6: Primary Differentiation + +The single most important way you are different from the alternative. This must be something the target customer cares about, not just something you're proud of. + +## Positioning Statement Examples + +### Example 1: Cloud Storage (Early Days of Dropbox) + +``` +For small business teams +who waste time emailing files back and forth and losing track of versions, +Dropbox is a file sharing service +that automatically syncs files across all devices. +Unlike emailing attachments or using USB drives, +Dropbox ensures everyone always has the latest version without any effort. +``` + +### Example 2: CRM for SMB + +``` +For B2B sales teams at companies with 10-50 reps +who lose deals because leads fall through the cracks in spreadsheets, +our product is a sales CRM +that ensures no lead goes unworked with automated follow-up sequences. +Unlike Salesforce, +our product requires zero admin and is fully functional within one day. +``` + +### Example 3: DevOps Monitoring + +``` +For site reliability engineering teams at mid-market SaaS companies +who are overwhelmed by alert noise and can't distinguish real incidents from false alarms, +our product is an incident management platform +that reduces mean time to resolution by 60%. +Unlike PagerDuty combined with manual runbooks, +our product automatically correlates alerts, identifies root cause, and suggests remediation steps. +``` + +## Market Alternative vs Product Alternative Positioning + +When entering the pragmatist market, you must choose a competitive frame of reference. There are two fundamental approaches: + +### Market Alternative Positioning + +**Frame your product against the way the market currently solves the problem.** The "alternative" is the status quo -- spreadsheets, manual processes, legacy systems, or a combination of point tools. + +**When to use:** +- You are creating a new product category +- There is no direct competitor doing what you do +- The status quo is painful and familiar to the target + +**Advantages:** +- Easy for the buyer to understand the problem you solve +- No direct competitor to fight +- Large addressable market (everyone using the old way) + +**Disadvantages:** +- Must educate on the new approach +- No existing budget line item for your category +- Buyers may not realize their current approach is the problem + +**Example:** "Unlike managing customer feedback in scattered Slack channels, email threads, and spreadsheets, our product centralizes all feedback in one system tied directly to your product roadmap." + +### Product Alternative Positioning + +**Frame your product against an established competitor in a recognized category.** You're saying "we do what they do, but better in this specific way." + +**When to use:** +- A recognized category and competitor exist +- The category has budget (it's in the buyer's plan) +- You have a clear, defensible advantage over the competitor + +**Advantages:** +- Buyer immediately understands what you do +- Existing budget line item +- Clear evaluation framework + +**Disadvantages:** +- You're compared on the competitor's terms +- Must differentiate on a dimension that matters +- Risk of being seen as a "me too" product + +**Example:** "Unlike HubSpot, which requires enterprise pricing for advanced automation, our product includes full marketing automation at mid-market price points with no feature gating." + +## Positioning for Pragmatists vs Visionaries + +This is the core positioning challenge of crossing the chasm. Your positioning must fundamentally change. + +### Messaging Shift Table + +| Element | Visionary Positioning | Pragmatist Positioning | +|---------|----------------------|------------------------| +| **Category** | New category, disruptive | Existing category, better approach | +| **Benefit** | Transformative potential | Measurable ROI | +| **Evidence** | Vision, demo, prototype | Case studies, references, data | +| **Risk framing** | "Risk of missing out" | "Low risk, proven approach" | +| **Language** | Revolutionary, paradigm shift | Proven, reliable, trusted | +| **Competitive frame** | "Nothing like this exists" | "Better than what you use today" | +| **Call to action** | "Be the first" | "Join 200 companies like yours" | +| **Pricing justification** | Strategic value | ROI calculation | + +### Example: Same Product, Different Positioning + +**The product:** AI-powered code review tool + +**Visionary positioning (for early adopters):** +"The future of software development. Our AI fundamentally reimagines code review, eliminating bottlenecks and enabling 10x developer velocity. Leading engineering teams at innovative companies are already transforming their development workflows." + +**Pragmatist positioning (for early majority):** +"For engineering teams spending 15+ hours per week on code review, our tool is an automated code review assistant that catches 80% of common issues before human review. Unlike manual-only code review, our tool reduces review cycle time by 40% and is used by 150 engineering teams including three Fortune 500 companies." + +Same product. Completely different positioning. The visionary version excites early adopters and terrifies pragmatists. The pragmatist version bores early adopters and reassures pragmatists. + +## Competitive Frame of Reference Selection + +### The Two-Competitor Framework + +Pragmatists evaluate by comparison. You need exactly two competitors in your positioning: + +1. **The market alternative:** What they do today (validates the problem) +2. **The product alternative:** The closest direct competitor (validates the category) + +Position yourself as the best of both worlds: + +- "We solve the problem that [market alternative] creates..." +- "...with the ease and completeness that [product alternative] lacks." + +### Example + +**Product:** Cloud-based contract management + +**Market alternative:** Storing contracts in shared drives and tracking renewals in spreadsheets +**Product alternative:** DocuSign CLM (enterprise, expensive, complex) + +**Positioning:** "For legal teams at mid-market companies who track contracts in spreadsheets and shared folders, our product is a contract management platform that eliminates missed renewals and reduces contract cycle time by 50%. Unlike enterprise solutions like DocuSign CLM that require 6-month implementations, our product deploys in two weeks with pre-built templates for your industry." + +## The "Admit Weakness" Technique + +Counter-intuitive but powerful for pragmatists: openly acknowledging a weakness increases credibility. + +### How It Works + +Pragmatists are skeptical. They've been burned by vendors who oversold. When you acknowledge a genuine limitation, you signal honesty, which makes the rest of your claims more believable. + +### Rules for Admitting Weakness + +1. **The weakness must be real** -- pragmatists can spot fake humility +2. **The weakness must be irrelevant to the buyer's primary need** -- don't admit a weakness that matters +3. **The strength must directly address the buyer's primary need** -- the admitted weakness creates contrast that highlights your key advantage + +### Example + +"We don't have the 500+ integrations that [competitor] has. If you need a platform that connects to everything, they might be a better fit. What we do have is the deepest integration with Salesforce on the market -- and for teams where Salesforce is the center of gravity, that depth matters more than breadth." + +**Why it works:** The pragmatist thinks "They're honest about limitations. That means I can trust their claims about Salesforce integration depth." + +## Repositioning When Crossing the Chasm + +### The Repositioning Process + +| Step | Action | Deliverable | +|------|--------|-------------| +| 1 | Audit current positioning | Document what you say today and how buyers categorize you | +| 2 | Interview beachhead segment | Understand how they describe their problem and evaluate solutions | +| 3 | Draft new positioning statement | Use the formula above | +| 4 | Test with 5-10 target buyers | "Does this describe something you'd evaluate?" | +| 5 | Align all materials | Website, pitch deck, sales scripts, content | +| 6 | Train the team | Everyone must speak the same language | +| 7 | Measure and iterate | Track win rates, sales cycle length, objections | + +### Common Repositioning Mistakes + +**Mistake 1: Keeping visionary language because it "sounds better"** +Your marketing team will resist removing words like "revolutionary" and "paradigm shift." Hold firm. Pragmatists read those words as "risky and unproven." + +**Mistake 2: Trying to position for both segments simultaneously** +"Revolutionary yet proven" is a contradiction. You can't be both. Choose pragmatist positioning and accept that visionaries won't be as excited. + +**Mistake 3: Choosing the wrong competitive frame** +If you position against a competitor that your target doesn't use or know, the positioning is meaningless. Always validate that your target actually uses/knows the alternative you name. + +**Mistake 4: Differentiating on a dimension the buyer doesn't care about** +"Our product uses Rust for 3x better performance" is a differentiator that matters to engineers, not to the VP of Marketing evaluating your tool. Differentiate on the dimension that matters to the buyer. + +## Testing Positioning with Target Customers + +### The Five-Minute Positioning Test + +Read your positioning statement to a target customer. Then ask: + +1. **"What do you think this product does?"** -- If they can't tell you, the positioning is unclear. +2. **"Is this a problem you have?"** -- If not, wrong target or wrong need statement. +3. **"What category would you put this in?"** -- If it doesn't match your intended category, reframe. +4. **"What would you compare it to?"** -- If the comparison is wrong, your competitive frame needs work. +5. **"Would you evaluate this?"** -- If no, the positioning isn't compelling enough. + +### Quantitative Testing + +Run A/B tests on your positioning: + +| Test | Method | Success Metric | +|------|--------|----------------| +| Landing page headline | A/B test old vs new positioning | Conversion rate | +| Cold email subject line | A/B test positioning-driven subject lines | Open and reply rate | +| Sales pitch | Track win rate with old vs new positioning | Win rate, deal size | +| Ad copy | Run both positioning variants as paid ads | CTR, CPA | + +### Positioning Audit Checklist + +- [ ] Does the target customer immediately self-identify? +- [ ] Is the need stated in the customer's language, not ours? +- [ ] Is the category one that already exists in the buyer's mind? +- [ ] Is there ONE key benefit, not a list? +- [ ] Is the competitive alternative something the buyer actually uses today? +- [ ] Is the differentiation something the buyer cares about (not just something we're proud of)? +- [ ] Does the full statement feel "boring" to our marketing team? (Good -- that means it's clear) +- [ ] Can every employee recite it consistently? +- [ ] Does it work in a cold email, a landing page, and a board presentation? diff --git a/.agents/skills/crossing-the-chasm/references/whole-product.md b/.agents/skills/crossing-the-chasm/references/whole-product.md new file mode 100644 index 00000000..1b174485 --- /dev/null +++ b/.agents/skills/crossing-the-chasm/references/whole-product.md @@ -0,0 +1,314 @@ +# The Whole Product Model + +Pragmatist buyers do not buy products. They buy solutions to problems. The gap between what you ship and what they need is called the "whole product gap," and it is the primary reason technology companies fail to cross the chasm. + +This reference provides the complete whole product framework, gap analysis tools, partnership strategies, and planning templates to ensure your offering meets the pragmatist's actual buying criteria. + + +## Table of Contents +1. [The Four Layers of the Whole Product](#the-four-layers-of-the-whole-product) +2. [Whole Product Gap Analysis Template](#whole-product-gap-analysis-template) +3. [Common Whole Product Gaps](#common-whole-product-gaps) +4. [Partnership Strategy for Filling Gaps](#partnership-strategy-for-filling-gaps) +5. [Industry Examples of Whole Product Evolution](#industry-examples-of-whole-product-evolution) +6. [Whole Product Planning Canvas](#whole-product-planning-canvas) +7. [Prioritizing Which Gaps to Fill First](#prioritizing-which-gaps-to-fill-first) + +--- + +## The Four Layers of the Whole Product + +### Layer 1: Generic Product + +What you ship out of the box. The core technology, the downloadable software, the API, the thing your engineering team built. + +**Characteristics:** +- What appears on your product spec sheet +- What you demo in sales calls +- What your engineers are proud of +- What innovators and early adopters evaluate + +**Reality check:** This is the only layer that matters to innovators. For everyone else, it is necessary but insufficient. + +### Layer 2: Expected Product + +The minimum configuration of products and services necessary for the buyer to achieve their basic purchasing objective. + +**Includes:** +- Core product plus essential configuration +- Basic documentation and getting-started guides +- Standard integrations with common tools +- Minimum viable support (email, knowledge base) +- Basic security and compliance features + +**Reality check:** If you don't deliver the expected product, customers churn within 90 days. This is table stakes. + +### Layer 3: Augmented Product + +The product fleshed out to provide the maximum chance of achieving the buyer's purchasing objective. This is what pragmatists actually evaluate when making a buying decision. + +**Includes everything in Expected, plus:** +- Deep integrations with the buyer's existing stack +- Professional services for implementation and migration +- Training programs and certification +- Industry-specific templates and configurations +- Dedicated support with SLAs +- Best practices documentation and playbooks +- Peer community and user groups +- Partner ecosystem for complementary capabilities + +**Reality check:** This is where the chasm lives. Early adopters buy the generic product. Pragmatists require the augmented product. Most companies fail to bridge this gap. + +### Layer 4: Potential Product + +The product's room for growth as more complementary products come to market and the product evolves. + +**Includes:** +- Platform extensibility and custom development +- Advanced features on the roadmap +- Ecosystem of third-party add-ons +- Future integrations and partnerships +- Innovation pipeline + +**Reality check:** The potential product matters for long-term positioning and valuation, but pragmatists buy based on the augmented product today, not the potential product tomorrow. + +## Whole Product Gap Analysis Template + +Use this template to identify the gaps between what you ship and what your beachhead segment needs. + +### Step 1: Map the Buyer's Complete Need + +Interview 5-10 target customers in your beachhead segment. Ask: + +- What does your end-to-end workflow look like today? +- What tools and systems are involved? +- Where are the manual handoffs and pain points? +- What would a complete solution look like? +- What would prevent you from adopting a new solution? +- What would need to be true for you to recommend this to a peer? + +### Step 2: Complete the Gap Analysis + +| Category | What Pragmatists Need | What We Ship Today | Gap | Severity (H/M/L) | Fill Strategy | +|----------|----------------------|--------------------|----|-------------------|---------------| +| **Core functionality** | | | | | | +| **Data integration** | | | | | | +| **Migration/onboarding** | | | | | | +| **Training** | | | | | | +| **Support** | | | | | | +| **Documentation** | | | | | | +| **Security/compliance** | | | | | | +| **Reporting/analytics** | | | | | | +| **Customization** | | | | | | +| **Industry adaptation** | | | | | | +| **Ecosystem/integrations** | | | | | | +| **Professional services** | | | | | | + +### Step 3: Classify Each Gap + +For each gap identified, classify the fill strategy: + +- **Build:** Add to your product roadmap (highest control, highest cost) +- **Partner:** Find a partner to provide the capability (moderate control, moderate cost) +- **Recommend:** Suggest a third-party tool and document the integration (lowest control, lowest cost) +- **Accept:** Acknowledge the gap and position around it (only for low-severity gaps) + +## Common Whole Product Gaps + +### Integration Gaps + +The most frequent gap. Pragmatists live in an existing ecosystem. Your product must work within it, not replace it. + +**Typical integration requirements:** +- CRM (Salesforce, HubSpot, Dynamics) +- ERP (SAP, Oracle, NetSuite) +- Identity provider (Okta, Azure AD, Google Workspace) +- Data warehouse (Snowflake, BigQuery, Redshift) +- Communication (Slack, Teams, email) +- File storage (Google Drive, SharePoint, Dropbox) +- Workflow automation (Zapier, Make, Power Automate) + +**Pragmatist expectation:** Native, maintained integrations -- not "you can use our API to build it yourself." + +### Training and Enablement Gaps + +Pragmatists need their teams to be productive quickly. They don't have time to figure it out. + +**Minimum training whole product:** +- Role-based onboarding guides (admin, end user, manager) +- Video tutorials for common workflows +- In-app guided tours +- Certification program for power users +- Train-the-trainer materials for enterprise rollouts +- Regular webinars on new features and best practices + +### Support Gaps + +**Early adopter expectation:** Slack channel with the founder. Responses in minutes. + +**Pragmatist expectation:** Tiered support with defined SLAs, escalation paths, dedicated account managers for enterprise, and a searchable knowledge base. + +| Support Tier | Response Time | Channel | For | +|-------------|---------------|---------|-----| +| Self-service | Instant | Knowledge base, community | All customers | +| Standard | 24 hours | Email, chat | Paid customers | +| Priority | 4 hours | Phone, chat | Enterprise customers | +| Critical | 1 hour | Dedicated line | Business-critical issues | + +### Migration and Onboarding Gaps + +Pragmatists are replacing something. The migration from their current solution must be low-risk and well-supported. + +**Migration whole product:** +- Data migration tools and scripts +- Migration planning guide with timelines +- Parallel running support (old and new system) +- Rollback plan if migration fails +- Dedicated migration support team +- Post-migration validation and cleanup + +### Compliance and Security Gaps + +Pragmatist organizations have procurement and security review processes. Missing any of these is a deal-killer: + +- [ ] SOC 2 Type II certification +- [ ] GDPR compliance documentation +- [ ] Data processing agreements +- [ ] Single sign-on (SSO) support +- [ ] Role-based access control (RBAC) +- [ ] Audit logging +- [ ] Data residency options +- [ ] Penetration test results +- [ ] Business continuity / disaster recovery documentation +- [ ] Insurance certificates (errors and omissions, cyber liability) + +## Partnership Strategy for Filling Gaps + +### Types of Whole Product Partners + +| Partner Type | What They Provide | Example | +|-------------|-------------------|---------| +| **Technology partners** | Integrations, complementary features | CRM, data warehouse, identity providers | +| **Service partners** | Implementation, training, customization | System integrators, consultancies | +| **Content partners** | Industry expertise, templates, best practices | Industry associations, domain experts | +| **Channel partners** | Distribution, trust, existing relationships | VARs, MSPs, consultancies | + +### Partner Selection Criteria + +- [ ] Do they serve our beachhead segment? +- [ ] Are they trusted by pragmatist buyers? +- [ ] Is the partnership mutually beneficial (not one-sided)? +- [ ] Can we execute a joint go-to-market? +- [ ] Do they fill a high-severity gap? +- [ ] Is the integration maintainable long-term? + +### Partnership Engagement Levels + +| Level | Commitment | Example | +|-------|-----------|---------| +| **Listing** | Directory listing, minimal integration | "Works with Salesforce" badge | +| **Integration** | Built and maintained API integration | Bi-directional data sync | +| **Co-marketing** | Joint content, webinars, case studies | "Better together" campaigns | +| **Co-selling** | Joint sales calls, bundled offerings | Combined solution for segment | +| **Embedded** | Deep product integration, shared roadmap | White-labeled capabilities | + +## Industry Examples of Whole Product Evolution + +### Example: Project Management Software (2010s) + +| Layer | 2012 (Generic) | 2016 (Expected) | 2020 (Augmented) | +|-------|----------------|------------------|-------------------| +| Core | Task lists, boards | Task lists, boards, timelines | Full work management platform | +| Integrations | API only | Slack, GitHub | 200+ native integrations | +| Templates | None | Basic templates | Industry-specific templates | +| Support | Email only | Email + chat | Tiered support with SLAs | +| Training | None | Help docs | Academy, certification | +| Compliance | None | Basic security | SOC 2, HIPAA, GDPR | +| Services | None | Basic onboarding | Professional services team | + +### Example: Marketing Automation (2000s-2010s) + +**Generic product:** Send emails to a list. + +**Whole product for mid-market B2B pragmatists:** +- Email sending with deliverability management +- CRM integration (Salesforce native) +- Lead scoring and routing +- Landing page builder (no developer needed) +- Campaign templates by industry +- ROI reporting tied to revenue +- Implementation services (60-90 day onboarding) +- Dedicated customer success manager +- User community and annual conference +- Agency partner ecosystem for execution +- Compliance with CAN-SPAM, GDPR + +The distance between "send emails" and the full list above is the whole product gap. HubSpot and Marketo won their respective segments by closing this gap faster than competitors. + +## Whole Product Planning Canvas + +Use this canvas to plan your whole product for the beachhead segment: + +### Section 1: Buyer Context + +- **Target segment:** [Your beachhead] +- **Primary buyer persona:** [Title, role, responsibilities] +- **Current solution:** [What they use today] +- **Primary pain:** [The specific problem costing them money/time] +- **Switching cost:** [What it takes to move from current to you] + +### Section 2: Whole Product Map + +| Component | Required? | Current State | Gap | Owner | Timeline | +|-----------|-----------|---------------|-----|-------|----------| +| Core product | Yes | | | Engineering | | +| Integration: [specific] | Yes | | | Engineering | | +| Integration: [specific] | Yes | | | Partner | | +| Migration tools | Yes | | | Engineering | | +| Onboarding program | Yes | | | Customer Success | | +| Training materials | Yes | | | Product Marketing | | +| Support infrastructure | Yes | | | Support | | +| Documentation | Yes | | | Technical Writing | | +| Compliance: [specific] | Yes | | | Security | | +| Professional services | Maybe | | | Services | | +| Industry templates | Maybe | | | Product | | + +### Section 3: Partnership Plan + +| Gap | Potential Partners | Partnership Level | Status | +|-----|-------------------|-------------------|--------| +| | | | | + +### Section 4: Timeline and Milestones + +| Milestone | Target Date | Dependencies | +|-----------|-------------|--------------| +| Whole product v1 (minimum for first pragmatist sales) | | | +| Whole product v2 (competitive with incumbents) | | | +| Whole product v3 (market-leading for segment) | | | + +## Prioritizing Which Gaps to Fill First + +Not all gaps are equally important. Use this prioritization framework: + +### Priority Matrix + +| | High frequency (most buyers need it) | Low frequency (some buyers need it) | +|---|---|---| +| **Deal-breaker (won't buy without it)** | Priority 1: Fill immediately | Priority 2: Fill within 6 months | +| **Preference (nice to have)** | Priority 3: Fill within 12 months | Priority 4: Monitor, fill if needed | + +### Identifying Deal-Breakers + +After every lost deal, ask: +- What was the primary reason you chose not to move forward? +- Was there a specific capability or requirement we did not meet? +- What would have changed your decision? + +Track these responses. When the same gap appears in 3+ lost deals from your beachhead segment, it is a Priority 1 gap. + +### The 80% Rule + +You do not need to fill every gap before selling to pragmatists. You need to fill the gaps that matter to 80% of your beachhead segment. The remaining 20% are either edge cases or can be handled with workarounds that pragmatists will accept if the core value proposition is strong enough. + +**The danger of perfectionism:** Waiting until the whole product is "perfect" means you never sell to pragmatists. Ship the 80% whole product, win your first 5-10 pragmatist customers, and iterate based on their feedback. diff --git a/.agents/skills/ddia-systems/SKILL.md b/.agents/skills/ddia-systems/SKILL.md new file mode 100644 index 00000000..beb1d22c --- /dev/null +++ b/.agents/skills/ddia-systems/SKILL.md @@ -0,0 +1,221 @@ +--- +name: ddia-systems +description: 'Design data systems by understanding storage engines, replication, partitioning, transactions, and consistency models. Use when the user mentions "database choice", "which database should I use", "SQL or NoSQL", "replication lag", "partitioning strategy", "consistency vs availability", "stream processing", "ACID transactions", "eventual consistency", "my queries are slow at scale", or "data is inconsistent across replicas". Also trigger when choosing a datastore, designing data pipelines, or debugging distributed-system consistency issues. Covers data models, batch/stream processing, and distributed consensus. For system design, see system-design. For resilience, see release-it.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Designing Data-Intensive Applications Framework + +A principled approach to building reliable, scalable, and maintainable data systems. Apply these principles when choosing databases, designing schemas, architecting distributed systems, or reasoning about consistency and fault tolerance. + +## Core Principle + +**Data outlives code.** Applications are rewritten and frameworks come and go, but data persists for decades -- prioritize the long-term correctness, durability, and evolvability of the data layer. Most applications are data-intensive, not compute-intensive: the hard problems are data volume, complexity, and rate of change, and explicit consistency/availability/latency trade-offs separate robust systems from fragile ones. + +## Scoring + +**Goal: 10/10.** Score a data architecture by the seven Quick Diagnostic rows below: award ~1.4 points per row answered "yes" with evidence (deliberate, documented trade-off), 0 where the answer is "no" or unknown. + +- **9-10:** every domain choice -- data model, storage engine, replication, partitioning, isolation, derived-data, fault handling -- is deliberate, documented, and matched to actual read/write/consistency requirements; failover tested. +- **5-6:** core choices made but two or three diagnostic rows fail -- e.g. default isolation level unknown, hot-key risk unhandled, or failover untested. +- **<=3:** choices driven by familiarity, not requirements; ignored failure modes (replication lag, write skew, hot partitions) and accidental complexity dominate. + +Report the current score, which diagnostic rows failed, and the improvements needed to reach 10/10. + +## The DDIA Framework + +Seven domains for reasoning about data-intensive systems: + +### 1. Data Models and Query Languages + +**Core concept:** The data model shapes how you think about the problem. Relational, document, and graph models each impose different constraints and enable different query patterns. + +**Why it works:** Choosing the wrong data model forces application code to compensate for representational mismatch, adding accidental complexity that compounds over time. + +**Key insights:** +- Relational models excel at many-to-many relationships and ad-hoc queries; document models at one-to-many relationships and locality; graph models at recursive traversals over interconnected data +- Schema-on-write (relational) catches errors early; schema-on-read (document) offers flexibility +- Polyglot persistence -- different stores for different access patterns -- is often the right answer +- Object-relational impedance mismatch is a real cost; document models reduce it for self-contained aggregates + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **User profiles with nested data** | Document model for self-contained aggregates | Profile, addresses, and preferences in one MongoDB document | +| **Social network connections** | Graph model for relationship traversal | Neo4j Cypher: `MATCH (a)-[:FOLLOWS*2]->(b)` for friend-of-friend | +| **Financial ledger with joins** | Relational model for referential integrity | PostgreSQL foreign keys between accounts, transactions, entries | + +See [references/data-models.md](references/data-models.md) when picking relational vs document vs graph or evaluating schema-on-read -- adds the full trade-off matrix and query-language comparisons. + +### 2. Storage Engines + +**Core concept:** Storage engines trade off read performance against write performance. Log-structured engines (LSM trees) optimize writes; page-oriented engines (B-trees) balance reads and writes. + +**Key insights:** +- LSM trees: append-only writes, periodic compaction, excellent write throughput, higher read amplification +- B-trees: in-place updates, predictable read latency, write amplification from page splits +- Write amplification (one logical write causing multiple physical writes) matters for SSDs with limited write cycles +- Column-oriented storage dramatically improves analytical queries through compression and vectorized processing +- In-memory databases are fast because they avoid encoding overhead, not because they avoid disk + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **High write throughput** | LSM-tree engine | Cassandra or RocksDB for time-series ingestion at 100K+ writes/sec | +| **Mixed read/write OLTP** | B-tree engine | PostgreSQL B-tree indexes for transactional point lookups | +| **Analytical queries** | Column-oriented storage | ClickHouse or Parquet for scanning billions of rows, few columns | + +See [references/storage-engines.md](references/storage-engines.md) when a workload is read/write-bound or you must choose indexes -- adds write/read-path diagrams, compaction strategies, column storage, and a benchmark-driven decision procedure. + +### 3. Replication + +**Core concept:** Replication keeps copies of data on multiple machines for fault tolerance, scalability, and latency reduction. The core challenge is handling changes consistently. + +**Why it works:** Every replication strategy trades off consistency, availability, and latency. Making the trade-off explicit prevents subtle anomalies that surface only under load or failure. + +**Key insights:** +- Single-leader: simple, strong consistency possible, but the leader is a bottleneck and single point of failure +- Multi-leader: better write availability across data centers, but complex conflict resolution +- Leaderless: highest availability via quorum reads/writes, but needs careful conflict handling +- Replication lag causes read-your-writes, monotonic-read, and causality violations +- Synchronous replication guarantees durability but adds latency; asynchronous risks data loss on failover +- CRDTs and last-writer-wins resolve conflicts with very different correctness guarantees + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Read-heavy web app** | Single-leader with read replicas | PostgreSQL primary + read replicas behind pgBouncer | +| **Multi-region writes** | Multi-leader replication | CockroachDB or Spanner with bounded staleness | +| **Shopping cart availability** | Leaderless with merge | DynamoDB with last-writer-wins or application-level cart merge | + +See [references/replication.md](references/replication.md) when choosing single/multi/leaderless or debugging stale reads -- adds lag anomalies, quorum math, conflict resolution, and CRDTs. + +### 4. Partitioning + +**Core concept:** Partitioning (sharding) distributes data across nodes so each handles a subset, enabling horizontal scaling beyond a single machine. + +**Key insights:** +- Key-range partitioning supports efficient range scans but risks hotspots on sequential keys +- Hash partitioning distributes load evenly but destroys sort order, making range queries expensive +- Local secondary indexes require scatter-gather queries; global secondary indexes require cross-partition updates +- Hotspots occur even with hashing when a single key is extremely popular (celebrity problem) +- Rebalancing strategies: fixed partition count, dynamic splitting, or proportional to nodes + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Time-series data** | Key-range partitioning by time + source | Partition by `(sensor_id, date)` to avoid current-day write hotspot | +| **User data at scale** | Hash partitioning on user ID | Cassandra consistent hashing on `user_id` for even distribution | +| **Celebrity/hot-key problem** | Key splitting with random suffix | Append random digit to hot key, fan out reads across 10 sub-partitions | + +See [references/partitioning.md](references/partitioning.md) when sharding or fighting a hot key -- adds rebalancing strategies, request routing, and local-vs-global secondary index trade-offs. + +### 5. Transactions and Consistency + +**Core concept:** Transactions provide safety guarantees (ACID) that simplify application code by letting you pretend failures and concurrency don't exist -- within the transaction's scope. + +**Why it works:** Without transactions, every piece of application code must handle partial failures, races, and concurrent modification. Transactions move that complexity into the database, handled correctly once. + +**Key insights:** +- Isolation levels are a spectrum: read uncommitted, read committed, snapshot isolation, serializable +- Most databases default to read committed or snapshot isolation -- NOT serializable -- so you must understand the anomalies this permits +- Write skew: two transactions read the same data, decide, and write different records -- no row lock prevents it +- Serializable snapshot isolation (SSI) gives full serializability optimistically: no blocking, but aborts on conflict; two-phase locking blocks and deadlocks under contention +- Distributed transactions (two-phase commit) are expensive and fragile; design around single-partition operations instead + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Account balance transfer** | Serializable transaction | `BEGIN; UPDATE accounts ... -100 WHERE id=1; UPDATE accounts ... +100 WHERE id=2; COMMIT;` | +| **Inventory reservation** | SELECT FOR UPDATE to prevent write skew | `SELECT stock FROM items WHERE id = X FOR UPDATE` before decrementing | +| **Cross-service operations** | Saga instead of distributed transaction | Charge card, reserve inventory; on failure, run compensating refund | + +See [references/transactions.md](references/transactions.md) when setting isolation levels or chasing a concurrency bug -- adds per-isolation anomaly tables, write-skew examples, 2PL vs SSI, and distributed-transaction pitfalls. + +### 6. Batch and Stream Processing + +**Core concept:** Batch processing transforms bounded datasets in bulk; stream processing transforms unbounded event streams continuously. Both compute derived data. + +**Why it works:** Separating the system of record from derived data (caches, indexes, materialized views) lets each be optimized independently and rebuilt from source when requirements change. + +**Key insights:** +- MapReduce is conceptually simple but operationally awkward; dataflow engines (Spark, Flink) generalize it with arbitrary DAGs +- Change data capture (CDC) turns database writes into a stream downstream systems can consume +- Stream-table duality: a stream is the changelog of a table; a table is the materialized state of a stream +- Exactly-once semantics require idempotent operations or transactional output +- Time windowing (tumbling, hopping, session) is essential for aggregating unbounded streams + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Daily analytics pipeline** | Batch processing with Spark | Read day's events from S3, aggregate, write to warehouse | +| **Real-time fraud detection** | Stream processing with Flink | Kafka payment events, rules over 5-second tumbling windows | +| **Syncing search index** | Change data capture | Debezium captures PostgreSQL WAL, Kafka feeds Elasticsearch | +| **Audit trail / event replay** | Event sourcing | Store `OrderPlaced`, `OrderShipped` events; rebuild state by replaying | + +See [references/batch-stream.md](references/batch-stream.md) when designing a pipeline or deriving data from a system of record -- adds dataflow engines, CDC wiring, windowing, and exactly-once techniques. + +### 7. Reliability and Fault Tolerance + +**Core concept:** Faults are inevitable; failures are not. A reliable system continues operating correctly even when individual components fail. Design for faults, not against them. + +**Key insights:** +- A fault is one component deviating from spec; a failure is the whole system stopping -- fault tolerance prevents the former becoming the latter +- Hardware faults are random and independent; software faults are correlated and systematic (more dangerous) +- Human error is the leading cause of outages -- minimize opportunity for mistakes, maximize ability to recover +- Timeouts are the fundamental fault detector, but tuning is hard: too short causes false positives, too long delays recovery +- Safety properties (nothing bad happens) must always hold; liveness (something good eventually happens) may be temporarily violated +- Byzantine fault tolerance is rarely needed outside blockchain; assume crash-stop or crash-recovery + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Service communication** | Timeouts + retries with backoff | `retry(max=3, backoff=exponential(base=1s, max=30s))` with jitter | +| **Leader election** | Consensus algorithm (Raft/Paxos) | etcd or ZooKeeper for distributed locks and leader election | +| **Graceful degradation** | Circuit breaker | Resilience4j: open circuit after 50% failures in 10-second window | + +See [references/fault-tolerance.md](references/fault-tolerance.md) when tuning timeouts/retries or adding consensus -- adds fault classification, timeout-tuning math, Raft/Paxos mechanics, and safety/liveness guarantees. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|------| +| **Choosing a database by popularity** | Engines have fundamentally different trade-offs | Match storage engine to actual read/write patterns | +| **Ignoring replication lag** | Stale reads, phantom reads, lost updates | Implement read-your-writes and monotonic-read guarantees | +| **Distributed transactions everywhere** | 2PC is slow, fragile; coordinator is a SPOF | Design single-partition operations; use sagas across services | +| **Hash partitioning everything** | Destroys range query ability | Key-range partitioning for time-series; composite keys for locality | +| **Assuming serializable isolation** | Defaults are weaker; write skew appears in production | Check the actual default; use explicit locking where needed | +| **Conflating batch and stream** | Wrong tool adds latency or wasted complexity | Match processing model to data boundedness and latency needs | +| **Treating all faults as recoverable** | Corruption and Byzantine faults need different handling | Classify faults; design a recovery strategy per class | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Can you explain why you chose this database over alternatives? | Choice was familiarity, not requirements | Evaluate data model fit, read/write ratio, consistency needs, scaling path | +| Do you know your database's default isolation level? | Latent concurrency bugs | Check docs; test for write skew and phantom reads | +| Is your replication strategy explicitly chosen? | Implicit consistency/durability assumptions | Document sync vs async, failover behavior, lag tolerance | +| Can your system handle a hot partition key? | One popular entity can down the cluster | Add key-splitting or load shedding for hot keys | +| Do you separate system of record from derived data? | Every change requires migrating everything | Introduce CDC or event sourcing to decouple | +| Are timeouts and retries tuned, not defaulted? | Cascading failures or needless delays | Measure p99; set timeouts above p99, below cascade threshold | +| Have you tested failover in production conditions? | Recovery plan is theoretical | Run chaos experiments: kill leaders, partition networks, fill disks | + +## Further Reading + +For the complete treatment with detailed diagrams and research references: + +- [*"Designing Data-Intensive Applications"*](https://www.amazon.com/Designing-Data-Intensive-Applications-Reliable-Maintainable/dp/1449373321?tag=wondelai00-20) by Martin Kleppmann + +## About the Author + +**Martin Kleppmann** is a distributed-systems researcher at the University of Cambridge and a former engineer at LinkedIn and Rapportive, known for his work on CRDTs and local-first software. His book *Designing Data-Intensive Applications* (2017) is the definitive reference for engineers building data systems, praised for making distributed-systems concepts accessible and practical. diff --git a/.agents/skills/ddia-systems/references/batch-stream.md b/.agents/skills/ddia-systems/references/batch-stream.md new file mode 100644 index 00000000..fa51cad1 --- /dev/null +++ b/.agents/skills/ddia-systems/references/batch-stream.md @@ -0,0 +1,342 @@ +# Batch and Stream Processing + +Data processing systems fall into three categories: services (online systems that handle requests), batch processing (offline systems that process large volumes of accumulated data), and stream processing (near-real-time systems that process data as it arrives). Understanding when and how to use batch and stream processing is essential for building data pipelines, analytics systems, and derived data stores. + + +## Table of Contents +1. [Batch Processing: MapReduce and Beyond](#batch-processing-mapreduce-and-beyond) +2. [Dataflow Engines: Beyond MapReduce](#dataflow-engines-beyond-mapreduce) +3. [Event Sourcing](#event-sourcing) +4. [Change Data Capture (CDC)](#change-data-capture-cdc) +5. [Stream-Table Duality](#stream-table-duality) +6. [Exactly-Once Semantics](#exactly-once-semantics) +7. [Time Windowing](#time-windowing) +8. [Architecture Patterns](#architecture-patterns) + +--- + +## Batch Processing: MapReduce and Beyond + +### The MapReduce Paradigm + +MapReduce, popularized by Google's 2004 paper, processes large datasets by breaking computation into two phases: + +1. **Map phase:** Read input data, extract key-value pairs. Each mapper processes a portion of the input independently. +2. **Shuffle phase:** Framework groups all values by key, distributing them to reducers. +3. **Reduce phase:** For each key, combine all values into a result. + +``` +Input: ["the cat sat on the mat"] + +Map: + "the" -> 1 + "cat" -> 1 + "sat" -> 1 + "on" -> 1 + "the" -> 1 + "mat" -> 1 + +Shuffle: Group by key + "the" -> [1, 1] + "cat" -> [1] + "sat" -> [1] + "on" -> [1] + "mat" -> [1] + +Reduce: Sum values + "the" -> 2 + "cat" -> 1 + "sat" -> 1 + "on" -> 1 + "mat" -> 1 +``` + +### MapReduce Strengths + +- **Horizontal scalability:** Add more machines to process larger datasets; the framework handles distribution +- **Fault tolerance:** If a mapper or reducer fails, the framework re-executes that task on another machine. Input data is immutable, so re-execution is safe. +- **Simplicity:** The programmer only writes map and reduce functions; the framework handles parallelism, distribution, and fault tolerance + +### MapReduce Weaknesses + +- **High latency:** Each MapReduce job reads from and writes to distributed storage (HDFS), adding significant I/O overhead +- **Chaining is awkward:** Complex computations require chaining multiple MapReduce jobs, each with its own read/write cycle +- **No iteration support:** Machine learning algorithms that iterate over data must launch a new MapReduce job for each iteration +- **Limited expressiveness:** Not all computations fit the map-reduce pattern naturally + +--- + +## Dataflow Engines: Beyond MapReduce + +### Apache Spark + +Spark replaces MapReduce with a more general computation model based on Resilient Distributed Datasets (RDDs) and directed acyclic graphs (DAGs) of operators. + +**Key improvements over MapReduce:** +- **In-memory processing:** Intermediate results stay in memory instead of being written to disk between stages +- **Arbitrary DAGs:** Computations can have multiple stages with various operators (map, filter, join, group, sort), not just map and reduce +- **Lazy evaluation:** Spark builds a computation plan before executing, enabling the optimizer to eliminate unnecessary steps +- **Iterative algorithms:** RDDs can be cached in memory and reused across iterations + +```python +# Spark: Word count +text_file = spark.read.text("hdfs://input/") +word_counts = (text_file + .select(explode(split(col("value"), " ")).alias("word")) + .groupBy("word") + .count() + .orderBy(desc("count"))) +word_counts.write.parquet("hdfs://output/") +``` + +### Apache Flink + +Flink treats batch processing as a special case of stream processing (a bounded stream). Its architecture is stream-first. + +**Key features:** +- **True streaming:** Processes events one at a time (not micro-batches like Spark Streaming) +- **Event-time processing:** Handles out-of-order events based on when they occurred, not when they arrived +- **Exactly-once semantics:** Provides exactly-once processing guarantees through checkpointing +- **Savepoints:** Snapshot the entire pipeline state for upgrades, scaling, or debugging + +### Comparison + +| Feature | MapReduce | Spark | Flink | +|---------|-----------|-------|-------| +| **Processing model** | Batch only | Batch + micro-batch streaming | Batch + true streaming | +| **Intermediate storage** | Disk (HDFS) | Memory (spills to disk) | Memory (checkpoints to disk) | +| **Latency** | Minutes to hours | Seconds to minutes | Milliseconds to seconds | +| **Fault tolerance** | Re-execute failed tasks | Recompute lost RDD partitions | Checkpoint-based recovery | +| **Best for** | Very large batch jobs | Interactive analytics, ML | Real-time streaming, event-time processing | + +--- + +## Event Sourcing + +### Concept + +Instead of storing the current state of an entity, store every state change as an immutable event. The current state is derived by replaying all events. + +``` +Traditional (mutable state): + Account { id: 1, balance: 150 } + +Event sourcing (immutable log): + AccountCreated { id: 1, balance: 0 } + MoneyDeposited { id: 1, amount: 200 } + MoneyWithdrawn { id: 1, amount: 50 } + + Current state = replay events: 0 + 200 - 50 = 150 +``` + +### Benefits + +- **Complete audit trail:** Every change is recorded with timestamp, actor, and context +- **Temporal queries:** "What was the balance on January 15?" Replay events up to that date +- **Event replay:** Rebuild read models, fix bugs by replaying with corrected logic, build new views from historical events +- **Debugging:** Reproduce any state by replaying the exact sequence of events +- **Decoupling:** Event producers and consumers can evolve independently + +### Challenges + +- **Event schema evolution:** Once events are stored, changing their schema is hard; use versioned event schemas +- **Eventual consistency:** Read models derived from events may lag behind the event log +- **Storage growth:** The event log grows forever; compaction or snapshotting is needed for old events +- **Complexity:** Building and maintaining projections (read models) adds architectural complexity + +### Event Store Implementations + +| Technology | Type | Key Feature | +|-----------|------|-------------| +| **EventStoreDB** | Purpose-built event store | Projections, subscriptions, optimistic concurrency | +| **Apache Kafka** | Distributed log | High throughput, log compaction, exactly-once semantics | +| **PostgreSQL** | Relational DB as event store | ACID transactions on event writes; LISTEN/NOTIFY for subscribers | +| **DynamoDB Streams** | Change stream | Automatic change capture from DynamoDB tables | + +--- + +## Change Data Capture (CDC) + +### Concept + +CDC observes all writes to a database and extracts them as a stream of change events that can be consumed by other systems. This keeps derived data stores (search indexes, caches, analytics databases) in sync with the source of truth. + +``` +Application -> PostgreSQL (source of truth) + | + v (CDC) + Kafka topic + / | \ + v v v + Elasticsearch Redis Data Warehouse + (search) (cache) (analytics) +``` + +### CDC Implementation Approaches + +| Approach | How It Works | Trade-off | +|----------|-------------|-----------| +| **Log-based (WAL parsing)** | Read the database's write-ahead log and extract changes | Most reliable; low overhead; captures all changes including those from direct SQL | +| **Trigger-based** | Database triggers write changes to an outbox table | Works with any database; adds write overhead; may miss changes from bulk operations | +| **Polling-based** | Periodically query for changed rows (using updated_at timestamp) | Simplest; misses deletes; can miss rapid changes between polls; adds query load | +| **Application-level** | Application explicitly writes events when modifying data | Full control; risk of forgetting to emit events; dual-write problem | + +### CDC Tools + +| Tool | Source Databases | Sink | Key Feature | +|------|-----------------|------|-------------| +| **Debezium** | PostgreSQL, MySQL, MongoDB, SQL Server, Oracle | Kafka | WAL-based; exactly-once; schema registry integration | +| **Maxwell** | MySQL only | Kafka, RabbitMQ, Redis | Lightweight; MySQL binlog parsing | +| **AWS DMS** | Most databases | Kafka, S3, Redshift, DynamoDB | Managed service; heterogeneous migration | +| **Fivetran/Airbyte** | Many sources | Data warehouses | Managed ELT platforms with CDC connectors | + +### The Dual-Write Problem + +A common anti-pattern is writing to two systems directly: + +``` +Application -> writes to PostgreSQL + -> writes to Elasticsearch + +Problem: If the Elasticsearch write fails after the PostgreSQL write succeeds, +the systems are now inconsistent. Retrying may cause duplicates. +``` + +**Solution:** Write to one system (PostgreSQL) and use CDC to propagate to the other. The CDC pipeline handles retries, ordering, and exactly-once delivery. + +--- + +## Stream-Table Duality + +### The Core Insight + +A stream and a table are two sides of the same coin: + +- **A stream is the changelog of a table.** If you record every INSERT, UPDATE, and DELETE to a table, that sequence of changes is a stream. +- **A table is the materialized state of a stream.** If you replay a stream of changes from the beginning, applying each change in order, you get the current table state. + +``` +Stream: + INSERT user {id: 1, name: "Alice"} + INSERT user {id: 2, name: "Bob"} + UPDATE user {id: 1, name: "Alice Chen"} + DELETE user {id: 2} + +Table (materialized from stream): + | id | name | + |----|-------------| + | 1 | Alice Chen | +``` + +### Practical Application: Kafka Log Compaction + +Kafka's log compaction feature retains only the latest value for each key, effectively converting a stream into a table snapshot: + +``` +Before compaction: + key=1, value="Alice" + key=2, value="Bob" + key=1, value="Alice Chen" + key=2, value=null (tombstone) + +After compaction: + key=1, value="Alice Chen" + (key=2 is deleted because value is null) +``` + +This allows a new consumer to read the compacted log and reconstruct the full current state without replaying the entire history. + +--- + +## Exactly-Once Semantics + +### The Challenge + +In distributed systems, messages can be lost, duplicated, or reordered. "Exactly-once" means that the effect of processing each message is reflected exactly once in the output, even in the presence of failures. + +### Achieving Exactly-Once + +True exactly-once requires coordination between the messaging system and the processing logic: + +| Approach | How It Works | Example | +|----------|-------------|---------| +| **Idempotent operations** | Design operations so that applying them multiple times has the same effect as applying once | `SET balance = 100` is idempotent; `INCREMENT balance BY 10` is not | +| **Transactional output** | Write output and update consumer offset in a single atomic transaction | Kafka Streams: transactional producer commits output records and consumer offsets together | +| **Deduplication** | Assign a unique ID to each message; recipient ignores messages it has already processed | Store processed message IDs in a set; check before processing | +| **Checkpointing** | Periodically save processing state; on failure, resume from last checkpoint | Flink savepoints: snapshot operator state and input positions | + +--- + +## Time Windowing + +### Why Windowing Matters + +Unbounded streams have no natural "end," so you can't wait for all data before computing an aggregate. Windowing divides the stream into finite chunks for aggregation. + +### Window Types + +| Window Type | How It Works | Use Case | +|------------|-------------|----------| +| **Tumbling** | Fixed-size, non-overlapping windows (e.g., every 5 minutes) | Hourly metrics, daily summaries | +| **Hopping** | Fixed-size windows that overlap (e.g., 10-minute windows every 5 minutes) | Smoothed averages, sliding computations | +| **Session** | Variable-size windows based on activity gaps (e.g., a session ends after 30 minutes of inactivity) | User session analytics, click streams | +| **Global** | A single window for the entire stream | Running totals, all-time aggregates | + +### Handling Late Events + +Events may arrive after their window has closed (due to network delays, buffering, or clock skew): + +- **Watermarks:** A timestamp that says "I believe all events before this time have arrived." Events arriving after the watermark are considered late. +- **Allowed lateness:** Accept late events up to a threshold (e.g., 1 hour after window closes), updating the window's result +- **Side outputs:** Route late events to a separate output for manual or delayed processing + +``` +Window: 10:00 - 10:05 +Watermark: 10:06 (all events before 10:06 expected) +Allowed lateness: 1 hour + +Event at 10:03 arriving at 10:07: accepted (within allowed lateness) +Event at 10:01 arriving at 11:30: discarded or sent to side output +``` + +--- + +## Architecture Patterns + +### Lambda Architecture + +Run both batch and stream processing pipelines in parallel: + +``` +Raw Data -> Batch Layer (Spark) -> Batch Views + -> Speed Layer (Flink) -> Real-time Views + +Query: Merge batch views + real-time views for complete result +``` + +**Pros:** Batch provides correctness; stream provides speed. +**Cons:** Maintaining two pipelines with the same logic is expensive and error-prone; results may differ between batch and stream. + +### Kappa Architecture + +Use a single stream processing pipeline for everything. Reprocess historical data by replaying the event log: + +``` +Event Log (Kafka) -> Stream Processor (Flink) -> Derived Views + +Reprocessing: Start a new consumer from the beginning of the log +``` + +**Pros:** Single codebase; simpler architecture; easier to reason about. +**Cons:** Reprocessing large histories can be slow; requires a durable, replayable log (Kafka with long retention). + +### Choosing Between Lambda and Kappa + +Use **Lambda** when: +- Exact correctness is required and stream processing approximations are unacceptable +- You have existing batch infrastructure and are adding streaming incrementally + +Use **Kappa** when: +- Your stream processing framework provides exactly-once guarantees +- You can afford to reprocess from the log when logic changes +- Simplicity and maintainability are priorities diff --git a/.agents/skills/ddia-systems/references/data-models.md b/.agents/skills/ddia-systems/references/data-models.md new file mode 100644 index 00000000..7771b5e5 --- /dev/null +++ b/.agents/skills/ddia-systems/references/data-models.md @@ -0,0 +1,262 @@ +# Data Models and Query Languages + +Choosing a data model is the most consequential architectural decision in an application. The data model shapes not only how data is stored, but how you think about the problem domain, what queries are natural, and how the system evolves over time. + +## The Relational Model + +### When Relational Excels + +The relational model, formalized by Edgar Codd in 1970, represents data as tables (relations) of rows (tuples) with typed columns (attributes). Its strength lies in: + +- **Many-to-many relationships:** Foreign keys and joins make it natural to represent complex relationships without data duplication +- **Ad-hoc queries:** SQL's declarative nature lets you ask any question without pre-planned access paths +- **Referential integrity:** Foreign key constraints enforce that references point to existing records +- **Transaction support:** ACID transactions with mature isolation levels are standard +- **Schema enforcement (schema-on-write):** The database rejects data that doesn't conform to the schema, catching errors early + +### Relational Anti-Patterns + +The relational model struggles with: + +- **Object-relational impedance mismatch:** Application objects don't map cleanly to flat tables; ORMs paper over this but add complexity +- **Deeply nested or tree-structured data:** Representing a resume with multiple jobs, each with multiple projects, each with multiple technologies requires many joins +- **Schema rigidity:** Adding a column to a table with billions of rows can be operationally expensive (though many databases now support instant `ADD COLUMN`) +- **Horizontal scaling:** Distributing joins across nodes is fundamentally hard + +### SQL as a Query Language + +SQL is declarative: you specify what you want, not how to get it. The optimizer chooses the execution plan, which means: + +- Query performance can improve without changing application code (when the optimizer or indexes improve) +- Complex queries are concise compared to imperative alternatives +- The optimizer can parallelize, reorder joins, and choose index strategies + +```sql +-- Find all users who placed an order in the last 30 days +-- and have a shipping address in California +SELECT DISTINCT u.name, u.email +FROM users u +JOIN orders o ON u.id = o.user_id +JOIN addresses a ON u.id = a.user_id +WHERE o.created_at > NOW() - INTERVAL '30 days' + AND a.state = 'CA' + AND a.type = 'shipping'; +``` + +This query would require nested loops, hash maps, and set operations in imperative code. SQL expresses the intent in six lines. + +--- + +## The Document Model + +### When Document Excels + +Document databases (MongoDB, CouchDB, Firestore) store data as self-contained documents, typically JSON or BSON: + +- **One-to-many relationships:** When a parent entity contains a list of child entities that are always accessed together, a document model avoids joins entirely +- **Data locality:** Reading a single document retrieves all related data in one disk seek, improving read performance for aggregate access +- **Schema flexibility (schema-on-read):** Each document can have a different structure; the application interprets the schema at read time +- **Natural fit for aggregates:** Domain-driven design aggregates map directly to documents + +### Document Example + +```json +{ + "user_id": "u-4829", + "name": "Alice Chen", + "email": "alice@example.com", + "addresses": [ + {"type": "home", "city": "San Francisco", "state": "CA"}, + {"type": "work", "city": "Palo Alto", "state": "CA"} + ], + "orders": [ + { + "order_id": "o-1001", + "items": [ + {"product": "Keyboard", "qty": 1, "price": 89.99}, + {"product": "Mouse", "qty": 2, "price": 29.99} + ], + "total": 149.97 + } + ] +} +``` + +Everything about a user is in one document. No joins needed for the common access pattern of "show me everything about this user." + +### Document Anti-Patterns + +- **Many-to-many relationships:** Without joins, you must denormalize (duplicate data) or perform multiple queries and join in application code +- **Cross-document references:** If order items reference a shared product catalog, updating a product name requires updating every document that embeds it +- **Large documents:** Documents that grow unboundedly (e.g., an array of all user events) cause write amplification because the entire document must be rewritten +- **Deep nesting:** Querying deeply nested fields is possible but awkward; updating nested fields requires careful path expressions + +--- + +## The Graph Model + +### When Graph Excels + +Graph databases (Neo4j, Amazon Neptune, JanusGraph) represent data as nodes (entities) and edges (relationships): + +- **Highly interconnected data:** Social networks, knowledge graphs, fraud detection, recommendation engines +- **Recursive traversals:** "Find all people within 3 degrees of connection" is natural in graph query languages but requires recursive CTEs or multiple joins in SQL +- **Heterogeneous data:** Nodes and edges can have different types and properties without schema changes +- **Path analysis:** Shortest path, centrality, community detection algorithms are built into graph engines + +### Graph Query Example (Cypher) + +```cypher +// Find mutual friends who live in the same city +MATCH (alice:Person {name: 'Alice'})-[:FRIENDS_WITH]->(mutual)<-[:FRIENDS_WITH]-(bob:Person {name: 'Bob'}) +WHERE mutual.city = alice.city +RETURN mutual.name, mutual.city +``` + +The equivalent SQL query would require self-joins and subqueries that obscure the intent. + +### Graph Anti-Patterns + +- **Simple CRUD operations:** Graph databases add overhead for straightforward create/read/update/delete without relationship traversals +- **Aggregation-heavy analytics:** Summing, counting, and grouping are more natural in SQL or column stores +- **Write-heavy workloads:** Graph index structures can be slower for bulk ingestion compared to LSM-tree stores + +--- + +## Schema-on-Write vs. Schema-on-Read + +| Aspect | Schema-on-Write (Relational) | Schema-on-Read (Document) | +|--------|------------------------------|---------------------------| +| **When schema is enforced** | At write time by the database | At read time by application code | +| **Error detection** | Immediate: bad data is rejected | Delayed: bad data is stored, fails at read | +| **Schema evolution** | ALTER TABLE (can be expensive) | Just start writing new fields | +| **Data quality** | Higher: database enforces constraints | Lower: application must validate | +| **Flexibility** | Lower: must define schema upfront | Higher: can iterate quickly | +| **Best for** | Structured data with known schema | Semi-structured data with evolving schema | + +### Practical Guidance + +Use schema-on-write when: +- Data integrity is critical (financial, medical, legal) +- Multiple applications share the same database +- You need complex queries across the dataset + +Use schema-on-read when: +- The schema is evolving rapidly (early-stage product) +- Data comes from external sources with varying structure +- Each record type is accessed as a self-contained unit + +--- + +## Query Languages Compared + +### SQL (Relational) + +Strengths: Mature, standardized, powerful optimizer, excellent tooling. +Weaknesses: Verbose for hierarchical data, recursive queries are awkward. + +### MongoDB Query Language (Document) + +```javascript +db.users.find({ + "addresses.state": "CA", + "orders.created_at": { $gte: ISODate("2024-01-01") } +}) +``` + +Strengths: Natural for document traversal, aggregation pipeline is powerful. +Weaknesses: No joins (until v3.2 $lookup, still limited), complex aggregations are hard to read. + +### Cypher (Graph) + +Strengths: Pattern matching for relationships, readable path expressions. +Weaknesses: Limited ecosystem, fewer tools and integrations. + +### MapReduce (Batch) + +```javascript +// Word count in MapReduce +map: function() { this.text.split(" ").forEach(w => emit(w, 1)); } +reduce: function(key, values) { return Array.sum(values); } +``` + +Strengths: Horizontally scalable, handles massive datasets. +Weaknesses: Low-level, hard to compose, high latency. + +--- + +## Data Model Evolution + +### Adding Fields + +- **Relational:** `ALTER TABLE users ADD COLUMN phone VARCHAR(20);` -- all rows get NULL until updated +- **Document:** Just start including `phone` in new documents; old documents simply lack the field +- **Graph:** Add a new property to nodes; existing nodes are unaffected + +### Changing Relationships + +- **Relational:** Add a junction table for many-to-many; migrate data +- **Document:** Restructure documents; may require a migration script for existing data +- **Graph:** Add new edge types between existing nodes + +### Breaking Changes + +In all models, renaming or removing fields requires backward-compatible migration: + +1. **Expand:** Add new field alongside old +2. **Migrate:** Backfill new field from old +3. **Contract:** Remove old field once all readers use new field + +This expand-migrate-contract pattern works regardless of data model. + +--- + +## Polyglot Persistence + +Most real-world systems benefit from using multiple data stores, each chosen for its strengths: + +| Use Case | Data Store | Reason | +|----------|-----------|--------| +| **Transactional records** | PostgreSQL | ACID, joins, referential integrity | +| **User sessions** | Redis | Sub-millisecond reads, TTL expiration | +| **Full-text search** | Elasticsearch | Inverted indexes, relevance scoring | +| **Activity feed** | Cassandra | High write throughput, time-series partitioning | +| **Recommendation graph** | Neo4j | Relationship traversal, path algorithms | +| **File/blob storage** | S3 | Unlimited capacity, durability | +| **Analytics** | ClickHouse/BigQuery | Column-oriented, fast aggregation | + +### Polyglot Challenges + +- **Data consistency:** How do you keep PostgreSQL and Elasticsearch in sync? Change data capture (CDC) is the standard answer +- **Operational complexity:** Each store requires monitoring, backup, and expertise +- **Query routing:** Application must know which store to query for which use case + +### When to Stay Monoglot + +Use a single database when: +- Your team is small and operational complexity is a bigger risk than suboptimal performance +- Your data fits comfortably in one model (most CRUD apps) +- Your query patterns are uniform (all point lookups, or all analytical scans) + +Add a second store only when you have measured evidence that the current store cannot serve a specific access pattern. + +--- + +## Data Model Migration Patterns + +### Relational to Document + +Common when an application starts with a relational database but finds that most queries fetch entire aggregate objects (user profiles, product listings) rather than joining across tables. The migration pattern: + +1. Identify aggregates that are always fetched together +2. Denormalize related tables into nested document structures +3. Accept data duplication for fields that are shared across aggregates (e.g., category names stored in both the category table and embedded in product documents) +4. Maintain a relational database for data that genuinely requires joins and referential integrity + +### Document to Relational + +Common when an application starts with a document database but discovers increasing need for cross-document queries, reporting, or referential integrity. Warning signs include frequent application-level joins, growing inconsistency from denormalized data, and complex aggregation queries that fight the document model. + +### Adding a Graph Layer + +When relationships between entities become a first-class concept (recommendations, fraud detection, knowledge graphs), adding a graph database alongside existing stores is often more practical than migrating. The graph database handles traversal queries while the primary store handles CRUD operations. Data synchronization between the stores is typically handled through CDC or periodic ETL jobs. diff --git a/.agents/skills/ddia-systems/references/fault-tolerance.md b/.agents/skills/ddia-systems/references/fault-tolerance.md new file mode 100644 index 00000000..911f848b --- /dev/null +++ b/.agents/skills/ddia-systems/references/fault-tolerance.md @@ -0,0 +1,333 @@ +# Reliability and Fault Tolerance + +Reliability means the system continues to work correctly even when things go wrong. Things going wrong are called faults, and a system that can cope with faults is called fault-tolerant. The distinction between a fault and a failure is critical: a fault is when one component of the system deviates from its specification, while a failure is when the system as a whole stops providing the required service. + + +## Table of Contents +1. [Faults vs. Failures](#faults-vs-failures) +2. [Types of Faults](#types-of-faults) +3. [Reliability Metrics](#reliability-metrics) +4. [Detecting Faults in Distributed Systems](#detecting-faults-in-distributed-systems) +5. [Byzantine Faults](#byzantine-faults) +6. [Safety and Liveness](#safety-and-liveness) +7. [Designing for Reliability](#designing-for-reliability) +8. [Practical Reliability Patterns](#practical-reliability-patterns) + +--- + +## Faults vs. Failures + +| Term | Definition | Example | +|------|-----------|---------| +| **Fault** | One component deviating from its specification | A disk sector becomes unreadable | +| **Failure** | The system as a whole stops providing the required service | The entire website goes down | +| **Fault tolerance** | Designing the system so that faults don't become failures | RAID mirrors data across disks so one disk fault doesn't cause data loss | + +The goal is not to prevent all faults (that is impossible) but to design systems that prevent faults from causing failures. + +--- + +## Types of Faults + +### Hardware Faults + +Hardware faults are random and largely independent. The probability that two unrelated hardware components fail at the same time is very low. + +| Component | Typical Failure Rate | Mitigation | +|-----------|---------------------|------------| +| **Hard disk** | MTTF ~10-50 years per drive | RAID, replicated storage | +| **RAM** | ~0.2% of DIMMs per year | ECC memory, replication | +| **Power supply** | Varies by quality | Dual power supplies, UPS, generators | +| **Network** | Partial failures common | Redundant paths, failover routing | +| **CPU** | Extremely rare | Multi-node redundancy | + +**Key insight:** As cluster sizes grow, hardware faults become common events. With 10,000 disks (MTTF 10 years), expect roughly 3 disk failures per day. Systems must handle hardware faults as routine events, not exceptional emergencies. + +### Software Faults + +Software faults are systematic and correlated. A bug that crashes one node is likely to crash all nodes running the same software. Software faults are more dangerous than hardware faults because they are correlated -- they affect many nodes simultaneously. + +**Common software faults:** +- A bug triggered by unusual input that crashes every instance processing that input +- A runaway process consuming all CPU, memory, or disk on every machine +- A cascading failure where one service's slowdown triggers timeouts in dependent services +- A leap second bug that affects every NTP-synchronized server simultaneously + +**Mitigations:** +- **Process isolation:** Run services in separate processes or containers so a crash in one doesn't affect others +- **Input validation:** Reject malformed input at the boundary before it reaches core logic +- **Circuit breakers:** Detect when a dependency is failing and stop sending requests, preventing cascade +- **Chaos engineering:** Deliberately inject faults to discover weaknesses before they cause outages +- **Gradual rollouts:** Deploy new code to a small percentage of servers first; monitor before rolling out widely + +### Human Errors + +Humans are the leading cause of outages. Studies show that configuration errors cause the majority of production incidents -- not hardware or software failures. + +**Mitigations:** +- **Design systems that minimize opportunity for error:** Well-designed APIs, admin interfaces, and configurations make it hard to do the wrong thing. Sensible defaults, validation, and dry-run modes. +- **Provide sandbox environments:** Allow engineers to experiment and test safely without affecting production. +- **Test at all levels:** Unit tests, integration tests, property-based tests, chaos tests. Automated testing catches errors that humans introduce. +- **Quick rollback:** Make it fast and easy to roll back a bad deployment. Feature flags allow disabling new code without redeploying. +- **Monitoring and alerting:** Detect problems early through metrics, dashboards, and alerts. If something goes wrong, you want to know in minutes, not hours. +- **Blameless postmortems:** Focus on systemic improvements, not individual blame. If a human error caused an outage, ask why the system allowed that error to cause an outage. + +--- + +## Reliability Metrics + +### Availability + +Availability is the percentage of time the system is operational: + +``` +Availability = Uptime / (Uptime + Downtime) +``` + +| Availability | Downtime per Year | Downtime per Month | +|-------------|-------------------|--------------------| +| **99% (two nines)** | 3.65 days | 7.3 hours | +| **99.9% (three nines)** | 8.76 hours | 43.8 minutes | +| **99.99% (four nines)** | 52.6 minutes | 4.38 minutes | +| **99.999% (five nines)** | 5.26 minutes | 26.3 seconds | + +**Key insight:** Each additional nine is roughly 10x harder to achieve. Going from 99.9% to 99.99% requires fundamentally different architecture, not just better operations. + +### Durability + +Durability is the probability that data, once written, will not be lost: + +- **S3 Standard:** 99.999999999% (11 nines) durability -- designed to sustain the loss of data in two facilities simultaneously +- **Single-disk:** ~99.5% over 5 years (depending on disk failure rate) +- **RAID-1:** ~99.99% over 5 years +- **Replicated across 3 data centers:** Approaches 11+ nines + +### Mean Time Between Failures (MTBF) and Mean Time To Recovery (MTTR) + +``` +Availability = MTBF / (MTBF + MTTR) +``` + +**Implication:** You can improve availability by either increasing MTBF (making failures less frequent) or decreasing MTTR (recovering faster). In practice, reducing MTTR is often more cost-effective because you can't eliminate all faults, but you can recover from them faster. + +--- + +## Detecting Faults in Distributed Systems + +### Timeouts + +Timeouts are the primary mechanism for detecting faults in distributed systems. If a node doesn't respond within the timeout period, it is considered failed. + +**The timeout dilemma:** +- **Too short:** False positives -- a slow but healthy node is declared dead, causing unnecessary failover, load redistribution, and potentially split-brain +- **Too long:** Slow detection -- a truly dead node continues to receive requests that fail, increasing latency and error rates for users + +**Choosing timeouts:** +- Measure the p99 response time of healthy nodes +- Set the timeout to p99 * 2 or p99 + a fixed margin (e.g., 1 second) +- Use adaptive timeouts that adjust based on observed latency (Phi Accrual Failure Detector) + +### Heartbeats + +Nodes periodically send heartbeat messages to indicate they are alive. If a heartbeat is missed, the node may be considered failed. + +``` +Node A -> Heartbeat every 1 second -> Monitor +Node B -> Heartbeat every 1 second -> Monitor + +If Monitor receives no heartbeat from Node B for 3 seconds: + -> Declare Node B potentially failed + -> Trigger health check or failover +``` + +**Heartbeat patterns:** +- **Push-based:** Each node sends heartbeats to a central monitor or to other nodes +- **Pull-based:** A monitor periodically polls each node for status +- **Gossip-based:** Each node gossips its status to random peers; failure information spreads epidemically + +### Failure Detectors + +A failure detector is an abstraction that encapsulates the logic of deciding whether a node is alive or dead. Properties of failure detectors: + +| Property | Meaning | +|----------|---------| +| **Completeness** | Every failed node is eventually detected | +| **Accuracy** | No healthy node is incorrectly declared failed | + +In asynchronous networks, no failure detector can guarantee both properties simultaneously. Practical failure detectors sacrifice accuracy (may occasionally declare healthy nodes as failed) to ensure completeness (never miss a truly failed node). + +--- + +## Byzantine Faults + +### What Are Byzantine Faults? + +A Byzantine fault occurs when a node behaves in an arbitrary and potentially malicious way: sending conflicting information to different peers, lying about its state, or corrupting data intentionally. + +### When Byzantine Fault Tolerance Matters + +| Context | Needed? | Why | +|---------|---------|-----| +| **Internal datacenter** | No | You trust your own servers; if one is compromised, you have bigger problems | +| **Public blockchain** | Yes | Participants are mutually untrusting; any node may be malicious | +| **Aerospace/nuclear systems** | Sometimes | Radiation can flip bits, causing non-crash arbitrary behavior | +| **Multi-organization systems** | Sometimes | If organizations don't trust each other, Byzantine tolerance may be needed | + +### Why Most Systems Ignore Byzantine Faults + +Byzantine fault tolerance requires 3f + 1 nodes to tolerate f Byzantine faults. This means tolerating 1 malicious node requires 4 nodes, and tolerating 2 requires 7. The overhead is substantial. + +Most systems instead assume a crash-stop or crash-recovery model: +- **Crash-stop:** A faulty node simply stops and never comes back +- **Crash-recovery:** A faulty node stops but may come back with its state intact (from durable storage) + +These simpler fault models are sufficient for the vast majority of data systems. + +--- + +## Safety and Liveness + +### Definitions + +| Property | Definition | Example | +|----------|-----------|---------| +| **Safety** | Nothing bad happens | No two nodes are elected leader simultaneously (no split-brain) | +| **Liveness** | Something good eventually happens | A failed node is eventually detected; a client request eventually receives a response | + +### Why the Distinction Matters + +In distributed systems, you can always guarantee safety properties, but liveness properties may be temporarily violated: + +- **Safety must always hold.** If a safety property is violated even once, the violation is irrecoverable. You can point to a specific moment when the property was violated. +- **Liveness may be temporarily violated.** A liveness violation means something hasn't happened yet, but it may happen in the future. You can't point to a specific moment when it was violated. + +**Example: Leader election** +- Safety: At most one leader at any time (must always hold) +- Liveness: A leader is eventually elected (may be temporarily violated during an election) + +### Practical Implications + +When designing distributed systems, prioritize safety over liveness: +- It is better for the system to be temporarily unavailable (liveness violation) than to produce incorrect results (safety violation) +- A consensus algorithm that never elects a leader is safe (no split-brain) but useless (no liveness) +- The art is achieving both safety and liveness under realistic assumptions about network and node behavior + +--- + +## Designing for Reliability + +### Defense in Depth + +No single mechanism provides complete reliability. Layer multiple defenses: + +``` +Layer 1: Input validation and sanitization +Layer 2: Application-level error handling and retries +Layer 3: Database transactions and constraints +Layer 4: Replication and failover +Layer 5: Backups and disaster recovery +Layer 6: Monitoring, alerting, and incident response +``` + +### Failure Mode Analysis + +For each component, ask: +1. **How can it fail?** (crash, slow down, return wrong answer, become unreachable) +2. **What happens when it fails?** (impact on dependent components and users) +3. **How will we detect the failure?** (monitoring, health checks, alerts) +4. **How will we recover?** (automatic failover, manual intervention, restore from backup) +5. **How do we prevent it?** (redundancy, testing, capacity planning) + +### Chaos Engineering Principles + +Chaos engineering proactively injects faults to discover weaknesses: + +| Experiment | What It Tests | Tools | +|-----------|--------------|-------| +| **Kill a node** | Failover and recovery | Chaos Monkey, kill -9 | +| **Network partition** | Partition tolerance, split-brain prevention | tc (traffic control), iptables, Toxiproxy | +| **Clock skew** | Time-dependent logic, lease expiration | libfaketime, NTP manipulation | +| **Disk full** | Logging, WAL, temporary files | dd, fallocate | +| **Slow responses** | Timeout handling, circuit breakers | Toxiproxy, tc netem | +| **DNS failure** | Service discovery fallback | iptables blocking port 53 | +| **Certificate expiration** | TLS handling, renewal processes | Short-lived test certificates | + +### The Recovery-Oriented Computing Approach + +Instead of trying to prevent all failures, optimize for fast recovery: + +1. **Micro-reboots:** Restart individual components instead of entire systems +2. **Undo support:** Every action has an undo; rollback is always available +3. **Redundancy at every level:** No single point of failure from hardware to application +4. **Monitoring is a first-class feature:** Not an afterthought; built into every component from day one +5. **Automation over documentation:** Runbooks become scripts; manual procedures become automated workflows + +--- + +## Practical Reliability Patterns + +### Retry with Exponential Backoff and Jitter + +```python +def retry_with_backoff(operation, max_retries=3, base_delay=1.0): + for attempt in range(max_retries): + try: + return operation() + except TransientError: + if attempt == max_retries - 1: + raise + delay = base_delay * (2 ** attempt) + jitter = random.uniform(0, delay * 0.5) + time.sleep(delay + jitter) +``` + +Jitter prevents thundering herd: if 1000 clients all retry at exactly the same time, they overload the recovering service. + +### Circuit Breaker + +``` +States: CLOSED -> OPEN -> HALF-OPEN -> CLOSED + +CLOSED: Requests pass through normally + -> If failure rate exceeds threshold: transition to OPEN + +OPEN: All requests immediately fail (fast fail, no network call) + -> After timeout period: transition to HALF-OPEN + +HALF-OPEN: Allow a small number of test requests + -> If test requests succeed: transition to CLOSED + -> If test requests fail: transition back to OPEN +``` + +### Bulkhead Pattern + +Isolate components so that a failure in one doesn't exhaust shared resources: + +``` +Thread Pool A (20 threads): Service A calls +Thread Pool B (20 threads): Service B calls +Thread Pool C (10 threads): Service C calls + +If Service B becomes slow and exhausts its 20 threads, +Services A and C are unaffected -- they have their own pools. +``` + +### Health Check Endpoints + +Every service should expose a health check endpoint that reports: + +```json +{ + "status": "healthy", + "checks": { + "database": {"status": "healthy", "latency_ms": 5}, + "redis": {"status": "healthy", "latency_ms": 1}, + "disk": {"status": "healthy", "free_gb": 42}, + "memory": {"status": "healthy", "used_percent": 65} + }, + "version": "2.3.1", + "uptime_seconds": 86400 +} +``` + +Load balancers and orchestrators (Kubernetes) use health checks to route traffic away from unhealthy instances and restart failing ones. diff --git a/.agents/skills/ddia-systems/references/partitioning.md b/.agents/skills/ddia-systems/references/partitioning.md new file mode 100644 index 00000000..6faa8e78 --- /dev/null +++ b/.agents/skills/ddia-systems/references/partitioning.md @@ -0,0 +1,294 @@ +# Partitioning + +Partitioning (also called sharding) divides a large dataset into smaller subsets called partitions, each stored on a different node. The goal is to spread data and query load evenly across machines, enabling horizontal scaling beyond the capacity of a single node. + +## Why Partition? + +A single database node has hard limits: +- **Storage capacity:** A single disk or SSD has a maximum size +- **Write throughput:** A single CPU can process a limited number of writes per second +- **Read throughput:** Even with caching, a single node can serve a limited number of concurrent reads + +Partitioning breaks through all three limits by distributing data across multiple nodes. Each node handles a fraction of the total workload. + +--- + +## Key-Range Partitioning + +### How It Works + +Assign a continuous range of keys to each partition, similar to volumes of an encyclopedia: + +``` +Partition 1: keys A-E +Partition 2: keys F-J +Partition 3: keys K-O +Partition 4: keys P-T +Partition 5: keys U-Z +``` + +The ranges are not necessarily evenly spaced -- they are chosen to distribute data evenly based on the actual key distribution. + +### Strengths + +- **Efficient range queries:** All keys in a range are on the same partition, so range scans are local and fast +- **Natural ordering:** Data is stored in sorted order within each partition, supporting ORDER BY queries +- **Good for time-series:** Partitioning by time range keeps recent data together + +### Weaknesses + +- **Hotspots on sequential keys:** If the partition key is a timestamp, all writes go to the partition for the current time period, creating a write hotspot +- **Uneven distribution:** Key ranges that looked balanced at partition creation may become skewed as data grows +- **Manual or complex rebalancing:** Range boundaries may need adjustment as data distribution changes + +### Avoiding Time-Series Hotspots + +Instead of partitioning by timestamp alone, use a composite key: + +``` +Partition key: (sensor_id, date) + +Sensor 1, 2024-01-01 -> Partition A +Sensor 2, 2024-01-01 -> Partition B +Sensor 1, 2024-01-02 -> Partition A +Sensor 3, 2024-01-01 -> Partition C +``` + +This distributes writes across partitions (different sensors go to different partitions) while preserving the ability to scan one sensor's data in time order. + +### Databases Using Key-Range Partitioning + +- HBase (row key ranges) +- Bigtable (row key ranges) +- MongoDB (range-based sharding option) + +--- + +## Hash Partitioning + +### How It Works + +Apply a hash function to the partition key and assign hash ranges to partitions: + +``` +hash(key) mod N = partition number + +hash("user_123") = 0x7A3F... -> Partition 3 +hash("user_456") = 0x1B2C... -> Partition 1 +hash("user_789") = 0xE4D1... -> Partition 5 +``` + +### Consistent Hashing + +Standard `hash mod N` is problematic when adding or removing nodes because it reassigns most keys. Consistent hashing solves this by mapping both keys and nodes onto a ring: + +``` +Ring positions: 0 ... 2^32 + +Nodes: A at position 1000, B at position 5000, C at position 9000 +Key: hash("user_123") = 3500 -> assigned to Node B (next node clockwise) +``` + +When a node is added or removed, only the keys between adjacent nodes are reassigned, minimizing data movement. + +### Virtual Nodes (Vnodes) + +Each physical node is assigned multiple positions (virtual nodes) on the ring, typically 256 per node. This: +- Distributes data more evenly (random positions may cluster otherwise) +- Enables proportional assignment (a more powerful node gets more virtual nodes) +- Smooths rebalancing (adding a node moves small chunks from many existing nodes) + +### Strengths + +- **Even distribution:** Hash functions distribute keys uniformly, avoiding hotspots from key distribution skew +- **Simple assignment:** Given the key, you can compute the partition without a lookup table + +### Weaknesses + +- **No range queries:** Hash destroys sort order, so range scans require querying all partitions (scatter-gather) +- **Hot keys still possible:** If one key receives disproportionate traffic (e.g., a celebrity's user ID), hashing doesn't help + +### Databases Using Hash Partitioning + +- Cassandra (default partitioner: Murmur3) +- DynamoDB (hash of partition key) +- Riak (consistent hashing) +- MongoDB (hash-based sharding option) + +--- + +## Secondary Index Partitioning + +When you need to query data by something other than the partition key, you need secondary indexes. There are two approaches to partitioning secondary indexes. + +### Local Secondary Indexes (Document-Partitioned) + +Each partition maintains its own secondary index covering only the data in that partition: + +``` +Partition 1: primary data A-M, local index on "color" +Partition 2: primary data N-Z, local index on "color" + +Query: SELECT * WHERE color = 'red' + -> Must query BOTH partitions (scatter-gather) + -> Each checks its local index + -> Results are merged +``` + +**Strengths:** +- Writes are local: updating the secondary index only affects one partition +- Simple to maintain: each partition is self-contained + +**Weaknesses:** +- Reads require scatter-gather across all partitions +- Latency is determined by the slowest partition (tail latency) + +**Used by:** MongoDB, Cassandra, Elasticsearch, SolrCloud + +### Global Secondary Indexes (Term-Partitioned) + +The secondary index is itself partitioned, but independently of the primary data: + +``` +Primary data: partitioned by user_id +Global index on "color": partitioned by color value + Index partition 1: color A-M (all reds across all primary partitions) + Index partition 2: color N-Z + +Query: SELECT * WHERE color = 'red' + -> Query index partition 1 only + -> Get list of document IDs + -> Fetch documents from their primary partitions +``` + +**Strengths:** +- Reads are efficient: query only the relevant index partition +- No scatter-gather for indexed queries + +**Weaknesses:** +- Writes require updating a remote partition (cross-partition write) +- Index updates are often asynchronous, meaning the index may be stale +- More complex distributed transaction requirements + +**Used by:** DynamoDB (global secondary indexes), Amazon Aurora + +--- + +## Rebalancing Strategies + +As data grows or nodes are added/removed, partitions must be rebalanced. + +### Strategy 1: Fixed Number of Partitions + +Create many more partitions than nodes (e.g., 1000 partitions for 10 nodes). Each node hosts multiple partitions. When a node is added, some partitions move from existing nodes to the new node. + +``` +Before: 3 nodes, 12 partitions (4 per node) +After adding node 4: 4 nodes, 12 partitions (3 per node) +Move 1 partition from each existing node to the new node +``` + +**Strengths:** Simple, no re-partitioning needed, proportional load balancing +**Weaknesses:** Must choose partition count upfront; too few means large partitions, too many means overhead + +**Used by:** Elasticsearch, Riak, Couchbase, Voldemort + +### Strategy 2: Dynamic Partitioning + +Start with one partition. When a partition grows beyond a threshold (e.g., 10GB), split it in half. When it shrinks below a threshold, merge it with a neighbor. + +**Strengths:** Adapts to data size automatically; no upfront sizing decisions +**Weaknesses:** Single partition at start means single-node bottleneck until first split; can cause split storms under rapid growth + +**Used by:** HBase, RethinkDB, MongoDB (with key-range sharding) + +### Strategy 3: Proportional to Nodes + +Keep a fixed number of partitions per node. When a node is added, it splits some existing partitions; when removed, its partitions are merged into others. + +**Strengths:** Partition count grows with cluster size; each partition stays manageable +**Weaknesses:** Splitting introduces brief unavailability for the affected partition + +**Used by:** Cassandra (with vnodes) + +--- + +## Request Routing + +How does a client know which node holds the partition for a given key? + +### Approach 1: Client-Side Routing + +The client knows the partition assignment and connects directly to the correct node: + +``` +Client: hash("user_123") -> Partition 3 -> Node B +Client connects directly to Node B +``` + +Requires the client to maintain a copy of the partition map. Used by Cassandra drivers. + +### Approach 2: Routing Tier (Proxy) + +A separate routing tier receives all requests and forwards them to the correct node: + +``` +Client -> Proxy -> determines partition -> forwards to correct Node +``` + +Used by: MongoDB (mongos router), Twemproxy (for Redis/Memcached) + +### Approach 3: Any-Node Contact + +Client contacts any node; that node forwards the request if it doesn't own the partition: + +``` +Client -> Node A -> "Not my partition" -> forwards to Node B +``` + +Used by: Cassandra (coordinator pattern), CockroachDB + +### Service Discovery + +All approaches need to know the current partition-to-node mapping. Options: + +- **ZooKeeper/etcd:** Centralized configuration service that tracks which partitions are on which nodes; nodes register themselves; routing layer watches for changes +- **Gossip protocol:** Nodes gossip partition assignments to each other; eventually consistent but no central point of failure +- **DNS-based:** Simple but slow to update; suitable only for coarse-grained routing + +--- + +## Handling Hotspots + +### Why Hotspots Occur + +Even with perfect hash distribution, application-level access patterns create hotspots: + +- **Celebrity problem:** A single user or entity receives vastly more traffic than others +- **Temporal hotspots:** Events cause sudden spikes on specific keys (product launch, breaking news) +- **Sequential keys:** Auto-incrementing IDs or timestamps concentrate writes + +### Mitigation Strategies + +| Strategy | How It Works | Trade-off | +|----------|-------------|-----------| +| **Key splitting** | Append random suffix (0-9) to hot keys; read from all 10 sub-keys and merge | 10x fan-out on reads; application complexity | +| **Write buffering** | Buffer writes to hot keys in memory; flush periodically | Eventual consistency; risk of data loss if buffer crashes | +| **Caching layer** | Cache hot reads in Redis/Memcached in front of the database | Stale data; cache invalidation complexity | +| **Rate limiting** | Limit requests to hot keys per client | Degrades user experience for hot content | +| **Application-level sharding** | Route hot entities to dedicated, scaled infrastructure | Operational complexity; special-case architecture | + +### Detecting Hotspots + +Monitor per-partition metrics: +- **Request rate per partition:** Compare against average; alert on 10x deviation +- **Latency per partition:** Hot partitions show higher p99 latency +- **CPU/IO utilization per node:** Uneven utilization signals partition skew +- **Key-level access counting:** Sample or log the most-accessed keys (most databases provide slow query logs or key-access statistics) + +### Automatic Hotspot Detection + +Some systems detect and mitigate hotspots automatically: +- **DynamoDB Adaptive Capacity:** Automatically isolates hot partitions onto dedicated throughput +- **Spanner:** Splits hot partitions when load exceeds threshold +- **CockroachDB:** Automatic range splitting and lease rebalancing based on load diff --git a/.agents/skills/ddia-systems/references/replication.md b/.agents/skills/ddia-systems/references/replication.md new file mode 100644 index 00000000..221bc177 --- /dev/null +++ b/.agents/skills/ddia-systems/references/replication.md @@ -0,0 +1,245 @@ +# Replication + +Replication means keeping a copy of the same data on multiple machines connected via a network. The reasons for replication are: keeping data geographically close to users (reduce latency), allowing the system to continue working even if some machines fail (increase availability), and scaling out the number of machines that can serve read queries (increase read throughput). + +## Single-Leader Replication + +### How It Works + +One node is designated the leader (primary, master). All writes go to the leader, which writes data to its local storage and sends the change to all followers (replicas, secondaries) via a replication log. Followers apply the changes in the same order. + +``` +Client Writes --> Leader --> Replication Log --> Follower 1 + --> Follower 2 + --> Follower 3 + +Client Reads --> Leader OR any Follower +``` + +### Synchronous vs. Asynchronous Replication + +| Mode | Behavior | Trade-off | +|------|----------|-----------| +| **Synchronous** | Leader waits for follower confirmation before acknowledging write to client | Guaranteed durability on follower; higher write latency; follower outage blocks writes | +| **Asynchronous** | Leader acknowledges write immediately after local write; replicates in background | Lower write latency; leader failure can lose confirmed writes; follower may be stale | +| **Semi-synchronous** | One follower is synchronous, rest are asynchronous | Guarantees data exists on at least two nodes; practical compromise | + +PostgreSQL, MySQL, and MongoDB all default to asynchronous replication. This means a write that the leader confirms can be lost if the leader crashes before replicating it. + +### Leader Failover + +When the leader fails, a follower must be promoted: + +1. **Detect failure:** Typically via heartbeat timeouts (e.g., no response for 30 seconds) +2. **Choose new leader:** Consensus among remaining nodes, or human intervention +3. **Reconfigure system:** Clients must send writes to the new leader; old leader must become a follower when it recovers + +**Failover dangers:** +- **Split-brain:** Two nodes both believe they are the leader; both accept writes, causing data divergence +- **Lost writes:** If the old leader had unreplicated writes, they are lost (or conflict with new leader's writes) +- **Stale routing:** Clients with cached leader addresses continue writing to the old leader + +--- + +## Replication Lag Problems + +Asynchronous replication introduces a delay between a write on the leader and its appearance on followers. This lag causes several anomalies. + +### Read-Your-Own-Writes Violation + +**Problem:** A user writes data (to the leader), then immediately reads it (from a follower that hasn't received the write yet). The user sees stale data and thinks their write was lost. + +**Solutions:** +- Read from the leader for data the user has recently modified (e.g., always read your own profile from the leader) +- Track the timestamp of the user's last write; only read from followers that are caught up to that timestamp +- Client remembers the position in the replication log of its last write and waits for the follower to reach that position + +### Monotonic Reads Violation + +**Problem:** A user makes two reads in sequence and sees time go backward -- the second read returns older data than the first because it hit a different, more-lagged follower. + +**Solutions:** +- Pin each user to a specific follower (session affinity) so consecutive reads go to the same replica +- Track the most recent read timestamp and ensure subsequent reads go to followers at least that current + +### Consistent Prefix Reads Violation + +**Problem:** Causally related writes appear out of order. A database stores a question and its answer; a reader sees the answer before the question because different partitions have different replication lag. + +**Solutions:** +- Ensure causally related writes go to the same partition +- Use causal consistency tracking (vector clocks or Lamport timestamps) + +--- + +## Multi-Leader Replication + +### Use Cases + +Multi-leader (active-active) replication allows writes at multiple data centers: + +- **Multi-datacenter operation:** Each data center has its own leader; writes are fast locally and replicated asynchronously to other data centers +- **Offline-capable clients:** A mobile app with a local database acts as a leader; syncs with server when online (CouchDB, PouchDB model) +- **Collaborative editing:** Each user's local state acts as a leader; changes are merged asynchronously + +### Conflict Resolution + +When two leaders accept conflicting writes to the same record, the conflict must be resolved: + +| Strategy | How It Works | Trade-off | +|----------|-------------|-----------| +| **Last writer wins (LWW)** | Assign a timestamp to each write; highest timestamp wins | Simple but discards concurrent writes; data loss is possible | +| **Merge values** | Combine conflicting values (e.g., union of sets) | Preserves data but only works for certain data types | +| **Application-level resolution** | Store all conflicting versions; let application code resolve | Most flexible but pushes complexity to the application | +| **CRDTs** | Use data structures mathematically guaranteed to converge | Automatic convergence; limited to specific data types (counters, sets, registers) | + +### Conflict Example + +``` +Leader A: UPDATE users SET name = 'Alice Chen' WHERE id = 42; +Leader B: UPDATE users SET name = 'Alice Wang' WHERE id = 42; + +LWW result: One name wins (other is silently lost) +Merge result: Not meaningful for names +CRDT (LWW-Register): Last timestamp wins, but the conflict is detected +Application resolution: Show user both versions, ask which is correct +``` + +--- + +## Leaderless Replication + +### How It Works + +In leaderless replication (used by Dynamo, Cassandra, Riak, Voldemort), there is no leader. Clients send writes to multiple replicas directly (or via a coordinator node). Reads also query multiple replicas and reconcile differences. + +### Quorum Reads and Writes + +Given `n` replicas, a write succeeds if acknowledged by `w` replicas, and a read succeeds if it reads from `r` replicas. As long as `w + r > n`, at least one of the read replicas will have the latest write. + +**Common configurations:** +- `n=3, w=2, r=2`: Tolerates 1 unavailable node for both reads and writes +- `n=3, w=3, r=1`: Fastest reads (only need one node), but writes require all nodes +- `n=3, w=1, r=3`: Fastest writes, but reads must query all nodes +- `n=5, w=3, r=3`: Tolerates 2 unavailable nodes + +### Sloppy Quorums and Hinted Handoff + +When a node is unavailable, a strict quorum would reject the write. A sloppy quorum instead writes to a different node temporarily. When the original node recovers, the temporary node forwards the data (hinted handoff). + +This improves write availability but weakens consistency guarantees -- `w + r > n` no longer guarantees reading the latest write because the writes may be on nodes outside the usual `n`. + +### Read Repair and Anti-Entropy + +Stale replicas need to be updated: + +- **Read repair:** When a read query detects a stale replica (by comparing versions), the client writes the latest value back to the stale replica +- **Anti-entropy process:** A background process continuously compares data between replicas and copies missing data. Unlike replication logs, this does not preserve ordering. + +--- + +## CRDTs: Conflict-Free Replicated Data Types + +### What CRDTs Are + +CRDTs are data structures that can be replicated across multiple nodes, where replicas can be updated independently and concurrently without coordination, and which mathematically guarantee eventual convergence. + +### Common CRDT Types + +| CRDT | Use Case | How It Works | +|------|----------|-------------| +| **G-Counter** | Counting (only increment) | Each node maintains its own counter; total = sum of all node counters | +| **PN-Counter** | Counting (increment and decrement) | Two G-Counters: one for increments, one for decrements; value = P - N | +| **G-Set** | Set (only add) | Union of all elements across all replicas | +| **OR-Set** | Set (add and remove) | Each element has unique tags; remove deletes specific tags | +| **LWW-Register** | Single value | Last write (by timestamp) wins | +| **MV-Register** | Single value | Keeps all concurrent versions; application resolves | + +### CRDT Example: Collaborative Counter + +``` +Node A starts: count = 0 +Node B starts: count = 0 + +Node A: increment -> local count_A = 1 +Node B: increment -> local count_B = 1 +Node B: increment -> local count_B = 2 + +After sync: +Both nodes: total = count_A + count_B = 1 + 2 = 3 +``` + +No conflicts, no coordination, mathematically correct. + +### CRDT Limitations + +- Only work for specific data types (not arbitrary business logic) +- Can grow in memory over time (tombstones, version vectors) +- Eventual consistency only -- no guarantee of when convergence happens +- Complex to implement correctly from scratch; use libraries (Automerge, Yjs, delta-state CRDTs) + +--- + +## Replication Topology Patterns + +### Single-Leader Topologies + +``` +Star: Leader --> F1, F2, F3, F4 (all followers connect to leader) +Chain: Leader --> F1 --> F2 --> F3 (each follower replicates to next) +``` + +Star is simpler; chain reduces load on the leader but increases replication delay. + +### Multi-Leader Topologies + +``` +All-to-All: A <--> B <--> C, A <--> C (every leader replicates to every other) +Star: A <--> B, A <--> C (one central leader relays) +Circular: A --> B --> C --> A (each sends to the next in a ring) +``` + +All-to-all is most fault-tolerant but creates more replication traffic. Circular and star topologies have single points of failure. + +--- + +## Practical Replication Configurations + +### PostgreSQL Streaming Replication + +``` +Primary (leader) --> Streaming Replication --> Standby 1 (sync) + --> Standby 2 (async) + --> Standby 3 (async) +``` + +- Write to primary; read from standbys for scaling +- Synchronous standby guarantees zero data loss on failover +- Asynchronous standbys may lag behind by seconds + +### Cassandra (Leaderless) + +``` +Client --> Coordinator Node --> Replica 1 (write) + --> Replica 2 (write) + --> Replica 3 (write) + +Read: Query 2 of 3 replicas (QUORUM), return most recent +``` + +- Replication factor (n) set per keyspace +- Consistency level (w, r) set per query +- Tunable consistency: `ONE` for speed, `QUORUM` for safety, `ALL` for strong consistency + +### Redis Sentinel (Single-Leader with Automatic Failover) + +``` +Master --> Replica 1 + --> Replica 2 + +Sentinel 1, Sentinel 2, Sentinel 3 (monitor master, vote on failover) +``` + +- Sentinels detect master failure via heartbeats +- Majority of sentinels must agree before promoting a replica +- Client library queries sentinel for current master address diff --git a/.agents/skills/ddia-systems/references/storage-engines.md b/.agents/skills/ddia-systems/references/storage-engines.md new file mode 100644 index 00000000..c234cb10 --- /dev/null +++ b/.agents/skills/ddia-systems/references/storage-engines.md @@ -0,0 +1,289 @@ +# Storage Engines + +A storage engine is the component of a database that handles how data is written to and read from disk (or memory). Understanding storage engine internals is essential for predicting performance, choosing appropriate indexes, and avoiding pathological workloads. + +## Two Families of Storage Engines + +All storage engines face a fundamental trade-off: optimizing for write performance or read performance. The two dominant approaches are log-structured engines (optimized for writes) and page-oriented engines (balanced reads and writes). + +--- + +## Log-Structured Engines: LSM Trees and SSTables + +### How LSM Trees Work + +LSM (Log-Structured Merge) trees use a multi-level structure: + +1. **Memtable:** An in-memory balanced tree (typically a red-black tree or skip list) that receives all writes +2. **Flush to SSTable:** When the memtable reaches a size threshold (typically 64MB-256MB), it is written to disk as a Sorted String Table (SSTable) -- a file of key-value pairs sorted by key +3. **Compaction:** Background processes merge multiple SSTables into fewer, larger SSTables, removing deleted keys and resolving duplicates + +### Write Path + +``` +Client Write + | + v +Write-Ahead Log (WAL) -- sequential append for durability + | + v +Memtable (in-memory sorted structure) + | + v (when full) +SSTable on disk (sorted, immutable file) + | + v (background) +Compaction: merge SSTables into larger, consolidated files +``` + +### Read Path + +``` +Client Read + | + v +Check Memtable (most recent writes) + | (miss) + v +Check Bloom Filters for each SSTable level + | (possible match) + v +Binary search within SSTable + | + v +Return value (or not found) +``` + +### Compaction Strategies + +| Strategy | How It Works | Trade-off | +|----------|-------------|-----------| +| **Size-tiered** | SSTables of similar size are merged together | Better write throughput; more space amplification | +| **Leveled** | SSTables are organized into levels of increasing size; each level is non-overlapping | Better read performance and space efficiency; higher write amplification | + +- **Cassandra** defaults to size-tiered compaction +- **RocksDB** and **LevelDB** use leveled compaction +- Choice depends on read/write ratio and disk space constraints + +### LSM Tree Strengths + +- **Sequential writes:** All disk writes are sequential appends, which is much faster than random I/O on both HDDs and SSDs +- **High write throughput:** Buffering in memory and batch-flushing to disk minimizes disk operations per write +- **Compression:** Sorted SSTables compress well, reducing storage costs +- **No fragmentation:** Compaction produces fresh, defragmented files + +### LSM Tree Weaknesses + +- **Read amplification:** A point read may need to check the memtable plus multiple SSTables at different levels +- **Write amplification:** A single logical write may be written and rewritten multiple times through compaction (typical: 10-30x) +- **Compaction interference:** Background compaction consumes CPU and I/O bandwidth, causing latency spikes if not tuned +- **Space amplification:** During compaction, both old and new SSTables exist temporarily, requiring 2x space + +### Databases Using LSM Trees + +- Cassandra, ScyllaDB, HBase (size-tiered) +- RocksDB, LevelDB (leveled) +- CockroachDB, TiKV (RocksDB-based) + +--- + +## Page-Oriented Engines: B-Trees + +### How B-Trees Work + +B-trees organize data in fixed-size pages (typically 4KB-16KB) arranged in a balanced tree structure: + +1. **Root page:** Contains keys and pointers to child pages +2. **Internal pages:** Contains keys that split the key space and pointers to child pages +3. **Leaf pages:** Contains the actual key-value pairs (or pointers to heap file rows) + +A B-tree with a branching factor of 500 and 4 levels can store up to 256TB of data (500^4 pages). + +### Write Path + +``` +Client Write + | + v +Write-Ahead Log (WAL) -- for crash recovery + | + v +Traverse B-tree from root to leaf + | + v +Update the leaf page in place + | (if page is full) + v +Split page: create two half-full pages, update parent pointer +``` + +### Read Path + +``` +Client Read + | + v +Start at root page + | + v +Binary search within page for correct child pointer + | + v +Follow pointer to next level + | (repeat log(n) times) + v +Reach leaf page, binary search for key + | + v +Return value +``` + +### B-Tree Strengths + +- **Predictable read latency:** Every lookup follows the same number of page accesses (tree depth), typically 3-4 for practical databases +- **Efficient point lookups:** O(log n) with small constants due to high branching factor +- **Mature and battle-tested:** 40+ years of optimization, well-understood behavior +- **Good range scan performance:** Leaf pages are often linked, allowing sequential scanning + +### B-Tree Weaknesses + +- **Write amplification:** Even a small update requires rewriting an entire page (typically 4KB-16KB) +- **Page splits:** When a page is full, it splits into two, requiring parent page updates (can cascade) +- **Fragmentation:** Over time, pages become partially full, wasting space +- **Concurrency control:** In-place updates require careful locking (latches) to prevent torn reads + +### Databases Using B-Trees + +- PostgreSQL, MySQL/InnoDB, Oracle, SQL Server +- SQLite +- Most traditional relational databases + +--- + +## LSM Trees vs. B-Trees: Decision Guide + +| Factor | LSM Trees | B-Trees | +|--------|-----------|---------| +| **Write throughput** | Higher (sequential writes) | Lower (random in-place updates) | +| **Read latency** | Less predictable (multiple levels) | More predictable (fixed tree depth) | +| **Space efficiency** | Better (compaction removes dead entries) | Worse (fragmentation, partial pages) | +| **Write amplification** | Higher (compaction rewrites) | Lower per write, but each write is a full page | +| **Compression** | Better (sorted data compresses well) | Moderate | +| **Concurrency** | No in-place updates, simpler | Requires page-level latching | +| **Maturity** | Newer, less predictable edge cases | Decades of production hardening | +| **Best for** | Write-heavy, append-heavy workloads | Mixed read/write OLTP | + +### Rules of Thumb + +- **Write-heavy with few reads:** LSM tree (Cassandra, RocksDB) +- **Read-heavy with indexed lookups:** B-tree (PostgreSQL, MySQL) +- **Mixed OLTP:** B-tree, unless write throughput is the bottleneck +- **Time-series ingestion:** LSM tree (high sequential write rate) +- **When in doubt:** Start with B-tree (PostgreSQL); it handles most workloads well + +--- + +## Column-Oriented Storage + +### The Problem with Row Storage for Analytics + +Analytical queries typically access a few columns across millions or billions of rows: + +```sql +SELECT product_category, SUM(revenue), COUNT(*) +FROM sales +WHERE sale_date BETWEEN '2024-01-01' AND '2024-12-31' +GROUP BY product_category; +``` + +In a row-oriented store, this query reads entire rows (all columns) even though it only needs three columns. With 100 columns and 1 billion rows, you read 100x more data than necessary. + +### How Column Storage Works + +Column-oriented storage stores each column separately: + +``` +Row store: Column store: +[id, name, age] ids: [1, 2, 3, ...] +[1, Alice, 30] names: [Alice, Bob, Carol, ...] +[2, Bob, 25] ages: [30, 25, 28, ...] +[3, Carol, 28] +``` + +### Column Storage Benefits + +- **I/O reduction:** Only read the columns your query needs +- **Compression:** Values in a single column have similar data types and distributions, enabling excellent compression (often 10:1) +- **Vectorized processing:** Modern CPUs process arrays of same-typed values much faster than individual rows (SIMD instructions) +- **Bitmap indexes:** Column values can be efficiently indexed with bitmaps for fast filtering + +### Column Storage Implementations + +| Database | Type | Key Feature | +|----------|------|-------------| +| **ClickHouse** | Column OLAP | MergeTree engine, real-time aggregation | +| **Apache Parquet** | File format | Columnar storage for Hadoop/Spark/data lakes | +| **Apache ORC** | File format | Optimized for Hive, predicate pushdown | +| **BigQuery** | Cloud OLAP | Serverless, automatic optimization | +| **Redshift** | Cloud OLAP | Zone maps, sort keys for pruning | +| **DuckDB** | Embedded OLAP | In-process, Parquet-native | + +--- + +## In-Memory Databases + +### Why In-Memory is Fast + +The performance advantage of in-memory databases is not simply "RAM is faster than disk." RAM-based systems are fast because they avoid the overhead of encoding data into disk-friendly formats. In-memory data structures (hash tables, skip lists, trees) can be used directly without serialization. + +### In-Memory Database Types + +| Database | Model | Persistence | Use Case | +|----------|-------|-------------|----------| +| **Redis** | Key-value, data structures | Optional (RDB snapshots, AOF log) | Caching, sessions, rate limiting, queues | +| **Memcached** | Key-value | None | Simple caching | +| **VoltDB** | Relational | Durable (WAL + replication) | High-throughput OLTP with serializability | +| **SAP HANA** | Relational + column | Durable | Mixed OLTP/OLAP | + +### Anti-Heap: Persistence for In-Memory Databases + +In-memory databases that need durability use several techniques: + +- **Write-ahead log (WAL):** Append every write to disk sequentially; on crash, replay the log +- **Periodic snapshots:** Write the entire in-memory state to disk at intervals +- **Replication:** Keep copies on other machines; if one crashes, another has the data +- **Battery-backed RAM:** Hardware guarantee that RAM contents survive power loss + +The WAL approach means writes are actually written to disk, but reads never touch disk. The disk serves only as a durability mechanism, not as a primary data structure. + +--- + +## Choosing a Storage Engine: Decision Framework + +### Step 1: Classify Your Workload + +| Question | Answer Determines | +|----------|-------------------| +| What is your read:write ratio? | LSM (write-heavy) vs. B-tree (balanced/read-heavy) | +| Do you need point lookups or range scans? | Hash index (point) vs. B-tree/LSM (range) | +| Is your data mostly queried by row or by column? | Row store (OLTP) vs. column store (OLAP) | +| Does your data fit in memory? | In-memory store for sub-millisecond latency | +| What latency percentile matters (p50 vs. p99)? | B-tree for predictable p99; LSM for better p50 | + +### Step 2: Consider Operational Factors + +- **Team expertise:** Use what your team knows unless there is a compelling reason to switch +- **Ecosystem:** Consider drivers, ORMs, monitoring tools, and backup solutions +- **Managed services:** Cloud-managed databases reduce operational burden significantly +- **Vendor lock-in:** Open-source engines provide more flexibility + +### Step 3: Test With Your Actual Workload + +Benchmarks from the internet are misleading. They test different hardware, different data sizes, different access patterns, and different configurations. The only benchmark that matters is one that uses your data, your queries, and your expected concurrency. + +Tools for benchmarking: +- **YCSB (Yahoo Cloud Serving Benchmark):** Standard workload generator for key-value stores +- **TPC-C:** Standard OLTP benchmark +- **TPC-H:** Standard OLAP benchmark +- **pgbench:** PostgreSQL-specific benchmark +- **sysbench:** MySQL-specific benchmark diff --git a/.agents/skills/ddia-systems/references/transactions.md b/.agents/skills/ddia-systems/references/transactions.md new file mode 100644 index 00000000..bb864b5b --- /dev/null +++ b/.agents/skills/ddia-systems/references/transactions.md @@ -0,0 +1,267 @@ +# Transactions and Consistency + +Transactions are an abstraction layer that simplifies the programming model for applications accessing a database. They bundle multiple reads and writes into a single logical operation that either succeeds completely (commit) or fails completely (abort), with no partial results visible to other operations. + +## ACID Properties + +### Atomicity + +**All or nothing.** If a transaction makes five writes and the system crashes after the third, atomicity guarantees that the first three are rolled back. The database is never left in a half-finished state. + +Atomicity is not about concurrency (that is isolation). Atomicity is about what happens when a fault occurs during a multi-step operation. + +### Consistency + +**Application invariants are preserved.** If your application requires that a credit and debit always sum to zero, consistency means the database won't allow a transaction that violates this rule. + +Note: Consistency is primarily an application-level property, not a database guarantee. The database can enforce certain invariants (foreign keys, unique constraints, check constraints), but most business rules must be maintained by application code. + +### Isolation + +**Concurrent transactions don't interfere.** Each transaction executes as if it were the only transaction running. The degree to which this is actually true depends on the isolation level. + +### Durability + +**Committed data is not lost.** Once a transaction commits, the data persists even if the system crashes, the power goes out, or disks fail. Implemented through write-ahead logs (WAL), replication, and backups. + +**Caveat:** No durability guarantee is absolute. Multiple disk failures, correlated software bugs, or accidental deletion can still cause data loss. Durability is a spectrum, not a binary property. + +--- + +## Isolation Levels + +Isolation levels define which concurrency anomalies the database prevents. Higher isolation levels prevent more anomalies but reduce concurrency and performance. + +### Read Uncommitted + +**Prevents:** Nothing meaningful. +**Allows:** Dirty reads (reading data written by an uncommitted transaction). + +Almost never used in practice. A transaction can read another transaction's in-progress, possibly-to-be-rolled-back writes. + +### Read Committed + +**Prevents:** Dirty reads, dirty writes. +**Allows:** Non-repeatable reads (reading the same row twice in one transaction yields different values because another transaction committed between the two reads). + +**How it works:** Reads see only committed data. Writes only overwrite committed data. Implemented with row-level locks for writes and returning the old committed value for reads. + +**Default in:** PostgreSQL, Oracle, SQL Server. + +```sql +-- Transaction 1 -- Transaction 2 +BEGIN; BEGIN; +SELECT balance FROM accounts + WHERE id = 1; -- returns 100 + UPDATE accounts SET balance = 200 + WHERE id = 1; + COMMIT; +SELECT balance FROM accounts + WHERE id = 1; -- returns 200 (non-repeatable read!) +COMMIT; +``` + +### Snapshot Isolation (Repeatable Read) + +**Prevents:** Dirty reads, dirty writes, non-repeatable reads. +**Allows:** Write skew, phantoms. + +**How it works:** Each transaction sees a consistent snapshot of the database as of the transaction's start time. Implemented with Multi-Version Concurrency Control (MVCC): the database maintains multiple versions of each row, and each transaction sees the version that was committed before the transaction started. + +**Default in:** MySQL (InnoDB calls it "repeatable read"), PostgreSQL (as "repeatable read", which is actually snapshot isolation). + +```sql +-- Transaction 1 sees a frozen snapshot +BEGIN; +SELECT balance FROM accounts WHERE id = 1; -- returns 100 +-- Even if another transaction changes balance to 200 and commits, +-- Transaction 1 still sees 100 for the rest of its lifetime +SELECT balance FROM accounts WHERE id = 1; -- still returns 100 +COMMIT; +``` + +**Key benefit:** Long-running reads (analytics, backups) don't block writes, and writes don't block reads. + +### Serializable + +**Prevents:** All concurrency anomalies. +**Guarantees:** Transactions execute as if they ran one after another, in some serial order. + +Three implementation approaches: + +#### Actual Serial Execution + +Run all transactions on a single CPU core, one at a time. + +**Strengths:** No concurrency bugs possible; simple implementation. +**Weaknesses:** Limited to single-core throughput; transactions must be short; no multi-statement interactive transactions. +**Used by:** VoltDB, Redis (single-threaded command execution). + +#### Two-Phase Locking (2PL) + +Readers block writers, and writers block readers. A transaction acquires locks as it reads and writes; it releases all locks only at commit or abort. + +**Strengths:** Provides true serializability. +**Weaknesses:** Poor performance under contention; deadlocks are possible and require detection/resolution; can severely limit concurrency. +**Used by:** MySQL (InnoDB serializable mode), DB2. + +``` +Transaction A: Acquires shared lock on row X (for reading) +Transaction B: Wants exclusive lock on row X (for writing) -> BLOCKED +Transaction A: Commits -> releases lock +Transaction B: Acquires exclusive lock, proceeds +``` + +**Deadlock example:** +``` +Transaction A: Lock row 1, then wants to lock row 2 +Transaction B: Lock row 2, then wants to lock row 1 +-> Deadlock! Database must abort one transaction. +``` + +#### Serializable Snapshot Isolation (SSI) + +An optimistic approach: transactions execute without blocking, and the database checks for conflicts at commit time. If a conflict is detected, one transaction is aborted and retried. + +**Strengths:** No blocking; reads never block writes; good performance under low contention. +**Weaknesses:** Under high contention, many transactions are aborted and retried, wasting work. +**Used by:** PostgreSQL (serializable mode since 9.1), CockroachDB. + +--- + +## Write Skew and Phantoms + +### Write Skew + +Write skew occurs when two transactions read the same data, make decisions based on it, and write to different records. No single row is written by both transactions, so row-level locks don't prevent it. + +**Classic example: On-call doctors** + +```sql +-- Rule: At least one doctor must be on call at all times +-- Currently: Alice and Bob are both on call + +-- Alice's transaction -- Bob's transaction +BEGIN; BEGIN; +SELECT count(*) FROM doctors SELECT count(*) FROM doctors + WHERE on_call = true; WHERE on_call = true; +-- count = 2, safe to remove one -- count = 2, safe to remove one +UPDATE doctors SET on_call = false UPDATE doctors SET on_call = false + WHERE name = 'Alice'; WHERE name = 'Bob'; +COMMIT; COMMIT; + +-- Result: NO doctors on call! Invariant violated. +``` + +Both transactions read count=2, both decided it was safe to go off-call, both committed. Neither wrote to the same row, so no row-level conflict was detected. + +### Phantoms + +A phantom occurs when a transaction's write changes the result set of another transaction's query. The write creates or removes rows that match the other transaction's WHERE clause. + +**Example: Meeting room booking** + +```sql +-- Transaction A -- Transaction B +BEGIN; BEGIN; +SELECT count(*) FROM bookings SELECT count(*) FROM bookings + WHERE room = 101 WHERE room = 101 + AND time = '2pm'; AND time = '2pm'; +-- count = 0, room is free -- count = 0, room is free +INSERT INTO bookings INSERT INTO bookings + (room, time, user) (room, time, user) + VALUES (101, '2pm', 'Alice'); VALUES (101, '2pm', 'Bob'); +COMMIT; COMMIT; +-- Double booking! +``` + +### Preventing Write Skew + +| Approach | How It Works | Limitation | +|----------|-------------|------------| +| **Serializable isolation** | Database detects and prevents all conflicts | Performance overhead | +| **SELECT FOR UPDATE** | Locks the rows that the decision is based on | Only works if there are existing rows to lock (doesn't prevent phantoms on non-existent rows) | +| **Materializing conflicts** | Pre-create rows that can be locked (e.g., create booking slots for every room-time combination) | Ugly, application-specific, error-prone | +| **Application-level locks** | Use an external lock service (Redis, ZooKeeper) | Moves complexity out of the database; risk of lock contention | +| **Unique constraints** | Database-enforced uniqueness prevents phantom inserts | Only works for simple cases | + +--- + +## Distributed Transactions + +### Two-Phase Commit (2PC) + +2PC coordinates a transaction across multiple nodes (or databases): + +**Phase 1 - Prepare:** +``` +Coordinator -> Node A: "Prepare to commit transaction T" +Coordinator -> Node B: "Prepare to commit transaction T" +Node A -> Coordinator: "Yes, I can commit" +Node B -> Coordinator: "Yes, I can commit" +``` + +**Phase 2 - Commit:** +``` +Coordinator -> Node A: "Commit transaction T" +Coordinator -> Node B: "Commit transaction T" +``` + +If any node votes "no" in phase 1, the coordinator sends "abort" to all nodes. + +### 2PC Problems + +- **Blocking:** If the coordinator crashes after sending "prepare" but before sending "commit/abort," participants are stuck holding locks, unable to commit or abort, potentially forever +- **Performance:** Two network round-trips plus lock holding time; 10-100x slower than single-node transactions +- **Single point of failure:** The coordinator is a critical dependency; its failure blocks all participants +- **In-doubt transactions:** Participants that voted "yes" in phase 1 cannot safely commit or abort without hearing from the coordinator + +### Alternatives to Distributed Transactions + +| Alternative | How It Works | Trade-off | +|-------------|-------------|-----------| +| **Saga pattern** | Break transaction into a sequence of local transactions; each step has a compensating transaction for rollback | No atomicity guarantee; compensating actions can be complex; eventual consistency | +| **Outbox pattern** | Write to the local database and an outbox table atomically; a separate process reads the outbox and publishes events | At-least-once delivery; consumers must be idempotent | +| **Event sourcing** | Store events as the source of truth; derive state from event log | Different programming model; eventual consistency for derived views | +| **Single-partition design** | Design your data model so that related data lives on the same partition | Constrains data model; may not work for all use cases | + +--- + +## Consensus and Distributed Agreement + +### The Consensus Problem + +Multiple nodes must agree on a value (e.g., who is the leader, whether a transaction should commit). Consensus must satisfy: + +- **Agreement:** All nodes decide the same value +- **Validity:** The decided value was proposed by some node +- **Termination:** All non-faulty nodes eventually decide +- **Integrity:** Each node decides at most once + +### Consensus Algorithms + +| Algorithm | Used By | Key Feature | +|-----------|---------|-------------| +| **Paxos** | Google (Chubby, Spanner) | Mathematically proven; notoriously hard to implement correctly | +| **Raft** | etcd, CockroachDB, TiKV | Designed for understandability; leader-based with log replication | +| **Zab** | ZooKeeper | Similar to Paxos; used for ZooKeeper's atomic broadcast | +| **Viewstamped Replication** | Academic | Predecessor to Raft; similar approach | + +### Practical Consensus: What You Actually Use + +Most applications don't implement consensus directly. Instead, they use consensus-based services: + +- **ZooKeeper/etcd:** Distributed key-value store with strong consistency; used for service discovery, leader election, distributed locks, configuration management +- **Consul:** Service mesh with consensus-based service catalog +- **Google Spanner:** Globally distributed database with external consistency (linearizability + serializable isolation) using TrueTime and Paxos + +### CAP Theorem in Practice + +The CAP theorem states that in the presence of a network partition (P), a system must choose between consistency (C) and availability (A). In practice: + +- **CP systems:** Sacrifice availability during partitions; refuse to serve requests if they can't guarantee consistency (e.g., ZooKeeper, HBase, Spanner) +- **AP systems:** Sacrifice consistency during partitions; continue serving requests with potentially stale data (e.g., Cassandra, DynamoDB, CouchDB) + +**Important nuance:** CAP is about the behavior during a network partition, which is a rare event. During normal operation, you can have both consistency and availability. The question is: what happens when the network fails? + +Most real-world systems are not purely CP or AP. They offer tunable consistency, where the application can choose per-operation whether to prioritize consistency or availability. diff --git a/.agents/skills/design-code-architecture/SKILL.md b/.agents/skills/design-code-architecture/SKILL.md new file mode 100644 index 00000000..9324abc4 --- /dev/null +++ b/.agents/skills/design-code-architecture/SKILL.md @@ -0,0 +1,207 @@ +--- +name: design-code-architecture +description: 'Guided journey from an app idea to a deliberate architecture: boundaries, domain model, data decisions, and resilience, making only the expensive-to-reverse decisions and deferring the rest. Orchestrates eight skills phase by phase - clean-architecture, domain-driven-design, system-design, ddia-systems, software-design-philosophy, release-it, pragmatic-programmer, 37signals-way - asking the user questions at every decision point and recording results in the project docs/ folder (ARCHITECTURE.md, RELIABILITY.md, DESIGN-CODE-ARCHITECTURE-PLAN.md) so the journey resumes across sessions. Use when the user wants to design a new app''s architecture, choose boundaries and a domain model before building, decide monolith versus microservices, or says ''how should I structure this app''. If a codebase already exists, use remove-technical-debt (aged) or improve-code-quality (fresh prototype); if the idea is not validated, run create-business or create-app first. For one framework in isolation, invoke that skill directly.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# Design Code Architecture + +Design the architecture for a new app: get the small number of expensive-to-reverse decisions right and stay aggressively simple everywhere else. This is an interactive, resumable journey of eight phases — the agent asks before every decision and records the outcome in your project's `docs/` folder, so you can stop after any phase and resume later. It runs from the most foundational and hardest-to-reverse (boundaries, domain) through the tunable (data, resilience) to the cross-cutting disciplines (complexity, reversibility, scope) you apply throughout. A weekend project uses three phases lightly; a funded team building toward launch wants the whole stack. + +## Core Principle + +**Architecture is the set of decisions that are expensive to reverse: make exactly those deliberately, and defer everything cheap.** This skill sequences the phases, asks the decision questions, and records every choice in `docs/`. The constituent skills carry the method — invoke them rather than improvising their frameworks. The whole strategy is to convert expensive decisions into cheap ones by putting a boundary in front of them, so the irreducibly expensive set stays small enough to get right with care. + +## Journey Map + +| Phase | Skill | Question it answers | Artifact | +|---|---|---|---| +| 1 | clean-architecture | Do source-code dependencies point inward — is the core testable with no DB, web, or framework? | Creates docs/ARCHITECTURE.md | +| 2 | domain-driven-design | Where does the business actually split, and what does each term mean? | Extends docs/ARCHITECTURE.md | +| 3 | system-design | How little system does our real load actually need? | Extends docs/ARCHITECTURE.md | +| 4 | ddia-systems | Which data model, storage engine, and consistency does each workload need? | Extends docs/ARCHITECTURE.md | +| 5 | software-design-philosophy | Is complexity hidden behind deep modules, or is this classitis? | Extends docs/TECH-DEBT.md | +| 6 | release-it | Will it degrade gracefully when a dependency is slow or down? | Creates docs/RELIABILITY.md | +| 7 | pragmatic-programmer | What thin slice proves the boundaries, and what habits keep them reversible? | Extends docs/TESTING.md + docs/TECH-DEBT.md | +| 8 | 37signals-way | What is essential for v1, and what speculative abstraction do we cut? | Extends docs/ARCHITECTURE.md + docs/TECH-DEBT.md | + +## Operating Rules + +1. **Resume first.** Before anything else, read `docs/DESIGN-CODE-ARCHITECTURE-PLAN.md` and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted. +2. **Intake on first run only.** No tracker: run the Intake below, then create `docs/DESIGN-CODE-ARCHITECTURE-PLAN.md` with every phase statused `pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason`. Done when the tracker exists and the user has confirmed the phase plan. +3. **Phase entry.** Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase `in-progress` on proceed. Done when the user chose. +4. **Skill invocation and fallback.** Invoke the phase's skill by its slug. If it is not available, offer: `npx skills add wondelai/skills/ --global`. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in. +5. **In-phase decisions.** Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect. +6. **Phase exit.** Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows `done`. +7. **Artifact discipline.** Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in `docs/`. Every recommendation lands as a checkbox or a table row with owner and priority. See [references/artifact-templates.md](references/artifact-templates.md) when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names. +8. **Every expensive-to-reverse decision gets a Decision Log row (decision, why, alternatives rejected) before any code assumes it.** Default to a modular monolith: services split only along proven bounded contexts. + +## Intake + +Ask these before creating the tracker: + +1. What will the app do, and what is the one feature that is genuinely your competitive advantage? (frames the core subdomain in Phase 2 — where to invest deep modeling versus buy off-the-shelf) +2. What stack are you leaning toward — language, web framework, ORM, database? (gates the Phase 1 boundary and Phase 4 data decisions; treated as a detail, never the skeleton) +3. What load is realistic in year one — rough daily active users and the main actions each takes? (gates Phase 3 sizing: requirements before solutions) +4. What outbound dependencies will it call — payments, email, LLM APIs, shipping, queues? (gates the Phase 6 integration-point audit) +5. Which data is the system of record, and are there second read patterns like search, analytics, or feeds? (gates Phase 4 consistency and derived-data decisions) +6. Has anyone validated that people actually want this app? (if not, route to create-business / create-app first — do not architect an unvalidated idea) +7. How many teams will own this system, and how much of the journey do you want now? (gates the team-topologies optional phase and the Phase 8 appetite) + +Phase-skip heuristics: skip Phase 3's scaling machinery and most of Phase 4's replication when year-one load is far below any threshold (a single indexed DB is the answer — record it and move on); skip the team-topologies optional phase for a single-team app. Never skip Phase 1 or Phase 2 — boundaries and the domain model are the additive work that makes every later decision cheap; Phase 6 resilience is not optional once real users and outbound calls exist. Then create the tracker from the template and confirm the plan. + +Done when `docs/DESIGN-CODE-ARCHITECTURE-PLAN.md` exists with every phase statused and the user has confirmed the plan. + +## Phases + +Phases run in the listed order, from hardest-to-reverse to tunable to cross-cutting — each assumes the previous phase's artifact exists. Any phase can be entered, skipped, or deferred per the Operating Rules; Phases 1-2 are the additive work that makes everything after them cheap to change. + +The phases form a dependency chain that mirrors the system: Domain-Driven Design says *where* the boundaries belong (contexts and aggregate seams); Clean Architecture says *which way* dependencies cross them; Data-Intensive Apps decides what lives inside them at the persistence layer; System Design says how much infrastructure that actually requires — usually far less than feared. Software Design keeps the modules deep instead of multiplying into shallow ceremony, Release It! hardens the integration points, Pragmatic Programmer supplies the cross-cutting habits that hold the structure over time, and the 37signals Way governs the whole thing by fixing time and cutting scope. + +### Phase 1 — Draw the boundaries (clean-architecture) + +**Purpose:** Keep business rules independent of the framework, database, and vendors so every later decision stays swappable — the move that buys back all the others. + +**Brief (fallback):** The Dependency Rule — source-code dependencies point inward: Frameworks → Interface Adapters → Use Cases → Entities; nothing inner names anything outer. Database, web, and vendors are details, plugins to your rules. Enforce with Dependency Inversion: a use case owns a repository interface; the Postgres/Stripe implementation lives in an outer adapter. Draw full boundaries only at real volatility (DB, external services, delivery); collapse layers elsewhere — direction matters, not folder count. + +**Invoke:** `clean-architecture` with a concrete first feature and the stack from intake. Ask it to layer that feature (entities, a use case with request/response models, repository + gateway interfaces, the HTTP controller and DB adapter in the outer ring), and to flag which boundaries are ceremony versus earning their cost at real volatility. + +**Decide with the user:** (1) Modular monolith versus services — default to a modular monolith with clean internal boundaries; a microservice with a shared data model is a distributed monolith, strictly worse. (2) Which volatility points get full boundaries with interfaces now versus collapsed layers. + +**Artifact:** Create docs/ARCHITECTURE.md with `## System Context` (what it does, integrations), `## Layer Map & Dependency Rule` (layers, what depends on what; violation | location | fix | status), and the monolith-versus-services choice in `## Decision Log` (date | decision | why | alternatives rejected). Update the tracker. + +**Done when:** the layer map exists, the first feature is layered with framework/ORM types confined to the outer ring, the core is designed to test with no DB/web/framework, the monolith-versus-services decision is a Decision Log row, and Phase 1 shows `done`. + +### Phase 2 — Model the domain (domain-driven-design) + +**Purpose:** Put boundaries where the business actually splits and make the code speak the domain — cheapest now, inventing the vocabulary from a blank page. + +**Brief (fallback):** The model is the code — build a Ubiquitous Language so team words are code words. Name after domain concepts (`Order.place()`, not `OrderManager.process()`); a name that resists is a design signal, not an annoyance. Bounded contexts: a region where a word means exactly one thing ("Customer" differs in billing versus support) — these are your future service seams. Aggregates: a small root cluster enforcing invariants, immediately consistent inside and eventually consistent outside; reference other aggregates by ID. Push behavior into entities — no anemic data bags. + +**Invoke:** `domain-driven-design` with the domain vocabulary and the Phase 1 layer map. Ask for the bounded-context map built from the words the team actually uses, the core aggregates with their invariants, and a subdomain classification (core / supporting / generic). + +**Decide with the user:** (1) Where the same word legitimately means different things across contexts — do NOT unify into one omniscient model. (2) Which subdomain is core (invest deep modeling) versus generic (buy or use OSS — auth, email, payments). + +**Artifact:** Extend docs/ARCHITECTURE.md: `## Bounded Contexts & Context Map` (contexts, relationships, anti-corruption layers) and `## Domain Glossary (Ubiquitous Language)` (term | meaning | code name); record aggregate and core-domain choices in `## Decision Log`. Update the tracker. + +**Done when:** contexts are mapped with their relationships, the glossary names the core terms, each aggregate states its invariants and by-ID references, the core subdomain is chosen, and the context boundaries line up with the Phase 1 layer map. + +### Phase 3 — Size the system honestly (system-design) + +**Purpose:** Prove with numbers how small the system can be, so you skip the machinery you cannot justify. + +**Brief (fallback):** Start with requirements, not solutions. Back-of-envelope: QPS = daily-active-users × actions/day ÷ 86,400, peak 2-5× average; storage = records/day × size × retention. For hundreds-to-thousands of users, a single indexed DB plus a read-path cache carries you a long time. Scale in order: vertical first, then cache-aside (TTL + explicit invalidation), then read replicas, and shard last, only with evidence. Reach for a message queue to decouple slow/spiky work, a CDN for global static assets. Premature sharding and premature service-splitting are named mistakes. + +**Invoke:** `system-design` with the load reality from intake. Ask for average and peak QPS, yearly storage, which component bottlenecks first, and a plain list of the techniques (sharding, replicas, CDN, queues, multi-region) you do NOT need yet. + +**Decide with the user:** Which scaling moves to make now versus defer — tied to the numbers (don't build for 50k users while at 50) — and the first slow workload, if any, to move behind a message queue. + +**Artifact:** Extend docs/ARCHITECTURE.md `## System Context` with the load reality and back-of-envelope numbers; record each scaling move (adopt now / defer with trigger) in `## Decision Log`. Update the tracker. + +**Done when:** average/peak QPS and yearly storage are written down, the first bottleneck is named, and every scaling technique is either adopted with a reason or deferred with the number that would trigger it. + +### Phase 4 — Make deliberate data decisions (ddia-systems) + +**Purpose:** Get the layer that outlives the code right — data model, storage engine, and consistency chosen by access pattern, not habit. + +**Brief (fallback):** Data outlives code. Match model to access pattern — relational for many-to-many and ad-hoc queries, document for self-contained aggregates with locality, graph for recursive traversals; storage engines trade reads against writes (LSM write-throughput versus B-tree read-latency). Most databases default to read-committed or snapshot, NOT serializable — naive read-then-write triggers write skew (two buyers taking the last unit). Lock explicitly (`SELECT ... FOR UPDATE`) or use a serializable transaction where invariants demand it. Single-leader + read replicas is the read-heavy default; replication lag forces deliberate read-your-writes. Separate system-of-record from rebuildable derived data. + +**Invoke:** `ddia-systems` with the workloads implied by the Phase 2 aggregates and the Phase 3 replica plan. Ask for a per-workload model + storage-engine fit, the actual default isolation level and its anomalies, and which read-then-write paths need locking. + +**Decide with the user:** (1) One datastore versus polyglot persistence, per workload fit. (2) Which paths get a lock or serializable transaction versus tolerate eventual consistency; whether a second read pattern (search, analytics) justifies derived data kept in sync by CDC. + +**Artifact:** Extend docs/ARCHITECTURE.md `## Data & Storage Decisions` (models, engines, isolation level, locked paths, system-of-record versus derived) and log the reasoning in `## Decision Log`. Update the tracker. + +**Done when:** each workload has a model + engine chosen by fit, the default isolation level is documented, every write-skew-prone path is locked or serializable, and any derived data has a defined sync mechanism. + +### Phase 5 — Keep modules deep (software-design-philosophy) + +**Purpose:** Stop the structure from becoming its own disease — hide machinery behind simple interfaces instead of shattering into shallow classes. + +**Brief (fallback):** Complexity is the enemy; the test for every decision is whether it makes the whole system simpler. Module depth = functionality ÷ interface complexity — deep modules hide power behind small interfaces; shallow ones (classitis) add interface cost without hiding complexity. Clean layering and deep modules are allies; clean layering and classitis are not. Information leakage — one design decision reflected in many modules — is a top red flag; encapsulate each piece of knowledge once. Strategic over tactical: invest 10-20% to keep the design clean; startup shortcuts compound into debt as the team grows. + +**Invoke:** `software-design-philosophy` with the module set proposed in Phases 1-2. Ask which modules are shallow pass-throughs to consolidate, where knowledge leaks across boundaries, and whether any planned boundary is ceremony rather than depth. + +**Decide with the user:** Which shallow modules to consolidate into deeper ones now, guarding against over-merging genuinely unrelated concerns; the design conventions the team adopts (naming, where behavior lives, one file per piece of knowledge). + +**Artifact:** Extend docs/TECH-DEBT.md `## Smell Inventory` (shallow-module / information-leakage entries with the consolidation applied) and record the agreed rules under `## Adopted Conventions`. Update the tracker. + +**Done when:** each shallow-module cluster is consolidated or logged with a fix, no single design decision is duplicated across modules, and the design conventions are written down. + +### Phase 6 — Design for failure (release-it) + +**Purpose:** Make the system degrade gracefully instead of collapsing when a dependency is slow or down — cheapest to design in now, not at 2 a.m. + +**Brief (fallback):** The software that passes QA is not what survives production. Integration points are the number-one killer and a slow response is worse than none — a hanging dependency exhausts threads and pools with nothing in the logs. Non-negotiable: connect + read timeouts on every outbound call; a circuit breaker on critical ones (trips open, fails fast, half-open recovery); bulkheads to isolate pools per dependency; retry with backoff + jitter. Paginate every list endpoint (unbounded result sets crash under real data); schedule steady-state cleanup. Decouple deploy from release with feature flags and backward-compatible expand-contract migrations. + +**Invoke:** `release-it` with the outbound dependencies from intake. Ask for timeout values and breaker thresholds per dependency, bulkhead placement, a graceful-degradation path per integration, and the deep-health-check + RED-metrics + expand-contract-migration essentials. + +**Decide with the user:** Breaker thresholds, which dependencies get dedicated pools, how core flows degrade when a non-critical dependency is down, and the rollback path you trust. Resist chaos engineering / multi-region failover for the first thousand users. + +**Artifact:** Create docs/RELIABILITY.md with `## Integration-Point Audit` (dependency | timeout | circuit breaker | bulkhead | retry policy | status), `## Query & Resource Findings`, `## Health Checks & Metrics`, and `## Deploy vs Release`. Update the tracker. + +**Done when:** every planned outbound call has a timeout, critical dependencies have breakers and bulkheads, every list endpoint is paginated, a deep health check + RED metrics + expand-contract migration + trusted rollback are specified, and the audit has no open rows for critical paths. + +### Phase 7 — Prove the wiring and lock in habits (pragmatic-programmer) + +**Purpose:** Build one thin real slice through every layer to prove the boundaries connect, and set the habits that keep the architecture reversible. + +**Brief (fallback):** Tracer bullet — build one thin but fully real vertical slice (HTTP → use case → repository → DB → back), kept as production code, for end-to-end feedback on day two and proof the boundaries link before you flesh them out. Reversibility: abstract every vendor behind your own interface (forking-road test — could you swap DB or LLM provider in a week?). Orthogonality: a dramatic change to one requirement should touch one module. DRY for knowledge, not coincidence — merge duplicated rules, leave look-alikes alone. Broken Window: fix the first hack or board it up with a tracked ticket. + +**Invoke:** `pragmatic-programmer` with the Phase 1 boundaries. Ask for the thinnest end-to-end tracer bullet that exercises every layer, an adapter interface for each vendor, and an audit of where one change would touch many modules or a vendor API would leak into business logic. + +**Decide with the user:** Which slice is the tracer bullet (one authenticated core action, minimal functionality); the broken-windows policy and debt budget per iteration; which vendors get an owned interface first. + +**Artifact:** Extend docs/TESTING.md `## Test Strategy`, `## Safety Net Map` (the tracer-bullet path as the first end-to-end test), and `## CI Gates`; extend docs/TECH-DEBT.md `## Debt Budget & Broken-Windows Policy` and `## Adopted Conventions` (reversibility, orthogonality). Update the tracker. + +**Done when:** the tracer-bullet slice runs end-to-end through every layer and is pinned as the first CI gate, each vendor sits behind an owned interface, and the broken-windows policy and debt budget are written down. + +### Phase 8 — Cut scope to the essential (37signals-way) + +**Purpose:** Decide whether any of this ships — fix time, flex scope, and delete speculative abstraction before it becomes complexity you carry. + +**Brief (fallback):** Build less — the best products do fewer things well; half a product beats a half-assed one. Fix an appetite (the time this work is genuinely worth) and cut scope to fit, rather than estimating an open-ended architecture that balloons. YAGNI: every speculative abstraction (generic plugin system, event sourcing, configurable multi-tenancy for zero users) is a decision deferred to an imaginary future at the cost of present complexity. Make tiny reversible decisions; say no by default so the great decisions breathe. Never cut the small set of expensive-to-reverse decisions. + +**Invoke:** `37signals-way` with the full architecture plan from Phases 1-7. Ask it to shape the work into a fixed appetite, separate essential-for-launch from gold-plating, name the rabbit holes, and list the speculative abstractions to delete or replace with the simplest thing that could work. + +**Decide with the user:** The appetite for v1 architecture work; which abstractions to cut now, defer with a revisit trigger, or replace with the simplest thing; confirm no expensive-to-reverse decision is being cut just to save time. + +**Artifact:** Extend docs/ARCHITECTURE.md `## Decision Log` with what is deliberately NOT built for v1; extend docs/TECH-DEBT.md `## Debt Ledger` (deferred abstractions as deliberately-taken debt, each with the trigger that would revisit it). Update the tracker. + +**Done when:** v1 scope is fixed to an appetite, every cut or deferred abstraction is a Decision Log or Debt Ledger row with a revisit trigger, and no expensive-to-reverse decision was cut for time. + +## Optional Phases + +| Skill | Add when | Artifact | +|---|---|---| +| team-topologies | More than one team will own the system, so module boundaries must align with team boundaries (Conway) | Extends docs/OPERATIONS.md (`## Team Structure`) | + +Optional phases follow the same operating rules; insert where the Add-when condition first becomes true — here, right after Phase 2, once the bounded contexts that team boundaries must mirror exist. + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Letting the framework be the architecture | Apply Clean Architecture's Dependency Rule (Phase 1) — framework calls inward; ORM and request types stay confined to the outer ring. | +| Over-engineering for scale you cannot prove you need | Run back-of-envelope QPS/storage math first (system-design, Phase 3); one indexed DB plus a cache is usually years of runway. | +| Over-correcting into classitis | Apply the deep-module rule (software-design-philosophy, Phase 5) — a few deep modules beat a swarm of shallow ones; boundaries at real volatility only. | +| Ignoring the database's actual consistency guarantees | Check the default isolation level and lock write-skew-prone paths (ddia-systems, Phase 4) — write skew passes every single-user test. | +| Treating resilience as a post-launch concern | Design timeouts, breakers, and pagination in from the start (release-it, Phase 6) — a slow dependency with no timeout freezes everything. | +| Confusing build-less with build-carelessly | Cut features and speculative abstractions (37signals-way, Phase 8), never the small set of expensive-to-reverse decisions. | + +## Completing the Journey + +Match the dose to the project: a weekend build leans on the Phase 1 Dependency Rule, a quick Ubiquitous Language, timeouts on outbound calls, and the Phase 8 instinct to cut scope — a few hours that save weeks. A funded team building toward launch works the whole stack, pulling the data and resilience phases in as real bottlenecks and integration points appear. + +Exit checklist — every box tied to an artifact: + +- [ ] Each expensive-to-reverse decision (boundaries, contexts, data/consistency) is a Decision Log row with alternatives rejected (ARCHITECTURE.md). +- [ ] Core business rules are designed to run with no DB, web, or framework (ARCHITECTURE.md Layer Map, no inward-pointing violations). +- [ ] Every outbound call has a timeout, critical ones have breakers, and every list is paginated (RELIABILITY.md Integration-Point Audit clear). +- [ ] A tracer-bullet slice proves the boundaries connect end-to-end and is the first CI gate (TESTING.md). +- [ ] v1 scope is fixed to an appetite with speculative abstractions cut or deferred with a trigger (TECH-DEBT.md Debt Ledger). + +Close the tracker: every phase `done` or `skipped: reason`, with remaining Next Actions carried into the ARCHITECTURE.md Decision Log and TECH-DEBT.md so nothing is lost. Then route forward: when the architecture serves a product that still needs validating and building, continue with `create-app`; when an existing prototype must be brought up to this structure, continue with `improve-code-quality`. diff --git a/.agents/skills/design-code-architecture/references/artifact-templates.md b/.agents/skills/design-code-architecture/references/artifact-templates.md new file mode 100644 index 00000000..8a50a3e6 --- /dev/null +++ b/.agents/skills/design-code-architecture/references/artifact-templates.md @@ -0,0 +1,86 @@ +# Artifact Templates — design-code-architecture + +Skeletons this metaskill creates in the user's `docs/` folder. Extend-only artifacts (TECH-DEBT.md, TESTING.md, OPERATIONS.md) are governed by the section headings named in each phase, not duplicated here. Copy a skeleton verbatim the first time you create its file; on later phases, extend the existing file — add or update your own sections, preserve everyone else's. + +## docs/DESIGN-CODE-ARCHITECTURE-PLAN.md (tracker) + +Created on first run; never shared with other journeys. The Phase Status table is pre-filled with this journey's real phases. + +```markdown +# Design Code Architecture Plan + +## Context +Intake answers, date started, project specifics (stack, core differentiator, year-one load, outbound dependencies, system of record, number of owning teams). + +## Phase Status +| Phase | Skill | Status | Artifact | Date | +|---|---|---|---|---| +| 1 — Draw the boundaries | clean-architecture | pending | ARCHITECTURE.md | | +| 2 — Model the domain | domain-driven-design | pending | ARCHITECTURE.md | | +| 3 — Size the system | system-design | pending | ARCHITECTURE.md | | +| 4 — Make data decisions | ddia-systems | pending | ARCHITECTURE.md | | +| 5 — Keep modules deep | software-design-philosophy | pending | TECH-DEBT.md | | +| 6 — Design for failure | release-it | pending | RELIABILITY.md | | +| 7 — Prove wiring, lock in habits | pragmatic-programmer | pending | TESTING.md + TECH-DEBT.md | | +| 8 — Cut scope to essential | 37signals-way | pending | ARCHITECTURE.md + TECH-DEBT.md | | +| Optional — Align teams to boundaries | team-topologies | pending | OPERATIONS.md | | +Statuses: pending · in-progress · awaiting-evidence · done · deferred: · skipped: + +## Key Decisions +| Date | Phase | Decision | Rationale | +|---|---|---|---| + +## Next Actions +- [ ] action (owner, due) +``` + +## docs/ARCHITECTURE.md + +Created in Phase 1; extended in Phases 2, 3, 4, and 8. System structure and decisions — includes the domain model and data decisions (no separate DATA.md or DOMAIN.md). + +```markdown +# Architecture + +## System Context +What the system does, key integrations, load reality (back-of-envelope numbers). + +## Layer Map & Dependency Rule +Layers, what depends on what, current violations. +| Violation | Location | Fix | Status | +|---|---|---|---| + +## Bounded Contexts & Context Map +Contexts, relationships, anti-corruption layers. + +## Domain Glossary (Ubiquitous Language) +| Term | Meaning | Code name | +|---|---|---| + +## Data & Storage Decisions +Data models, storage engines, isolation levels, replication, system-of-record vs derived data. + +## Decision Log +| Date | Decision | Why | Alternatives rejected | +|---|---|---|---| +``` + +## docs/RELIABILITY.md + +Created in Phase 6. Production hardening status. + +```markdown +# Reliability + +## Integration-Point Audit +| Dependency | Timeout | Circuit breaker | Bulkhead | Retry policy | Status | +|---|---|---|---|---|---| + +## Query & Resource Findings +Unbounded result sets, missing LIMITs/pagination, blocked threads. + +## Health Checks & Metrics +Deep health checks · RED metrics · symptom-based alerts. + +## Deploy vs Release +Feature flags, expand-contract migrations, rollback plan. +``` diff --git a/.agents/skills/design-everyday-things/SKILL.md b/.agents/skills/design-everyday-things/SKILL.md new file mode 100644 index 00000000..83cd4052 --- /dev/null +++ b/.agents/skills/design-everyday-things/SKILL.md @@ -0,0 +1,294 @@ +--- +name: design-everyday-things +description: 'Apply foundational design principles: affordances, signifiers, constraints, feedback, and conceptual models. Use when the user mentions "why is this confusing", "affordance", "error prevention", "discoverability", "human-centered design", "mental model", "mapping", "seven stages of action", "users keep making mistakes", "this is unintuitive", or "people cant figure out how to use it". Also trigger when reducing product complexity or feature creep. Covers the gulfs of execution and evaluation. For usability scoring, see ux-heuristics. For iOS-specific patterns, see ios-hig-design.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Design of Everyday Things Framework + +Foundational design principles for creating products that are intuitive, discoverable, and understandable. The "bible of UX" — applicable to physical products, software, and any human-designed system. + +## Core Principle + +**Good design is actually a lot harder to notice than poor design, in part because good designs fit our needs so well that the design is invisible.** When something fails, users blame themselves — but the fault is almost always in the design. Great design bridges the gap between what people want to do and what the product allows: it is discoverable (you can figure out what to do) and understandable (you can figure out what happened). + +## Scoring + +**Goal: 10/10.** Score 2 points per satisfied row of the Quick Diagnostic (5 rows = discoverability, evaluation, error recovery, mapping, constraints). Bands: **9-10** = users act without instructions, understand every outcome, and recover from any error; **5-6** = one gulf or error path is broken; **<=3** = users must consult a manual or routinely blame themselves. Report the current score and the diagnostic rows failing it. + +## The Two Gulfs + +Every interaction with a product requires bridging two gulfs: + +``` +USER PRODUCT + │ │ + ├──── Gulf of Execution ────────────────→│ + │ "How do I do what I want?" │ + │ │ + │←──── Gulf of Evaluation ──────────────┤ + │ "What happened? Did it work?" │ +``` + +### Gulf of Execution + +**The gap between what users want to do and what the product lets them do.** Users ask: What can I do here? Which control do I use? + +**Bridge with:** clear signifiers, natural mappings, constraints, familiar conceptual models. + +### Gulf of Evaluation + +**The gap between what the product did and what users understand happened.** Users ask: What happened? Did it work? What state is the system in? + +**Bridge with:** immediate visible feedback, clear system-state indicators, meaningful error messages, progress indicators. + +**Design goal:** Make both gulfs as narrow as possible — action and understanding should be immediate. + +See: [references/two-gulfs.md](references/two-gulfs.md) for gulf analysis exercises. + +## Seven Fundamental Design Principles + +### 1. Discoverability + +**Definition:** Can users figure out what actions are possible and how to perform them? Its five components — affordances, signifiers, constraints, mappings, feedback — are detailed below. + +**Test:** Put a new user in front of your product. If they can't figure out what to do within 10 seconds, discoverability is broken. + +**Anti-pattern:** "The user manual explains it." If users need a manual, the design failed. + +### 2. Affordances + +**Definition:** The relationship between an object's properties and a user's capabilities that determines how the object could be used. + +**Key insight:** Affordances exist whether or not they are perceived — what matters for design is *perceived* affordance. + +| Type | Definition | Example | +|------|------------|---------| +| **Real** | Physical capability exists | A button affords pressing | +| **Perceived** | User believes capability exists | A raised area looks clickable | +| **Hidden** | Exists but isn't obvious | Right-click context menu | +| **False** | Appears to afford action but doesn't | Decorative element that looks clickable | +| **Anti-affordance** | Prevents action | A barrier that blocks movement | + +**Digital applications:** + +| Element | Affordance | How to Signal | +|---------|------------|---------------| +| **Button** | Clicking/tapping | Raised, colored, shadow, hover state | +| **Text field** | Text input | Border, placeholder text, label | +| **Scroll area** | Scrolling | Scroll bar, fade at edge, partial content | + +**Common failures:** flat design erasing perceived affordances (button or label?), too-small touch targets, interactive and decorative elements that look identical. + +See: [references/affordances.md](references/affordances.md) for affordance design patterns. + +### 3. Signifiers + +**Definition:** Signals that communicate where the action should take place. **Affordances determine what you CAN do; signifiers show you WHERE and HOW.** + +| Type | Definition | Example | +|------|------------|---------| +| **Deliberate** | Designed to communicate | "Push" label on door, placeholder text | +| **Accidental** | Unintentional but informative | Worn path in grass (people walk here) | +| **Social** | Other people's behavior | Line of people indicates entrance | + +**Digital signifiers:** + +| Signifier | What It Communicates | Example | +|-----------|---------------------|---------| +| **Cursor change + hover state** | This is interactive | Pointer → hand on links; button color change | +| **Icons + labels** | Function of the element | Magnifying glass = search; "Submit", "Cancel" | +| **Color + position** | Status, category, hierarchy | Red = error, green = success; close button top-right | + +**Design rule:** When in doubt, add a signifier — better to over-communicate than leave users guessing. + +See: [references/signifiers.md](references/signifiers.md) when deciding which signifier to add to an unclear control. + +### 4. Mappings + +**Definition:** The relationship between controls and their effects. **Natural mapping** means the spatial layout of controls matches the layout of what they control. + +| Mapping Quality | Example | Why It Works/Fails | +|-----------------|---------|-------------------| +| **Natural** | Volume slider (up = louder) | Matches mental model | +| **Poor** | Light switch panel | No spatial correspondence to lights | +| **Poor** | Stovetop knobs in a row | Layout doesn't match burner positions | + +**Digital principles:** controls near what they affect, layout mirroring content, direction matching expectation (scroll down = content moves up), related controls grouped. + +| Technique | How It Works | Example | +|-----------|-------------|---------| +| **Proximity** | Control near target | Edit button next to content | +| **Spatial** | Layout mirrors real world | Map controls match compass directions | +| **Cultural** | Follows conventions | Red = stop/danger, green = go/safe | +| **Sequential** | Follows natural order | Steps 1, 2, 3 left to right (or top to bottom) | + +See: [references/mappings.md](references/mappings.md) for mapping analysis exercises. + +### 5. Constraints + +**Definition:** Limiting the possible actions to prevent errors. + +| Type | Mechanism | Example | +|------|-----------|---------| +| **Physical** | Shape/size prevents wrong action | USB plug only fits one way | +| **Cultural** | Social norms guide behavior | Red means stop, green means go | +| **Semantic** | Meaning restricts options | A rearview mirror only makes sense facing backward | +| **Logical** | Logic limits choices | Only one hole left for the last screw | + +**Digital constraints:** + +| Constraint | Implementation | Example | +|------------|---------------|---------| +| **Input validation** | Restrict what can be entered | Date picker vs. free text | +| **Disabled states** | Gray out unavailable options | "Submit" disabled until form valid | +| **Forced sequence + undo** | Steps in order; allow reversal | Wizard with locked steps; Gmail "Undo send" | + +**Design rule:** Every constraint you add is one less error the user can make — make wrong actions impossible rather than punishing them. + +See: [references/constraints.md](references/constraints.md) for constraint design patterns. + +### 6. Feedback + +**Definition:** Communicating the results of an action back to the user. Feedback must be immediate (within 0.1s for direct manipulation), informative, appropriately dosed, and non-intrusive. + +| Type | When to Use | Example | +|------|-------------|---------| +| **Visual** | Most actions | Button press animation, color change, checkmark | +| **Auditory** | Important events, confirmations | Success chime, error sound | +| **Haptic** | Touch devices, confirmation | Vibration on key press | +| **Progress** | Long operations | Progress bar, spinner, skeleton screen | + +**Digital feedback patterns:** + +| Situation | Feedback Needed | Example | +|-----------|----------------|---------| +| **Form submission** | Success/error message | "Saved!" toast or inline error | +| **Loading** | Progress indicator | Spinner, skeleton screen, percentage | +| **Error** | What went wrong + how to fix | "Invalid email. Please check format." | + +**Response times:** 0.1s feels instantaneous; 1s is a noticeable delay (change cursor); 10s loses attention (show progress bar); over 10s users leave (show percentage, allow backgrounding). + +**Common failures:** no feedback (did my click register?), delayed feedback (feels broken), unclear feedback, alert overload. + +See: [references/feedback.md](references/feedback.md) when an action gives no clear result and you need the right feedback type and timing. + +### 7. Conceptual Models + +**Definition:** The user's mental model of how a product works. + +| Model | Held By | Description | +|-------|---------|-------------| +| **Design model** | Designer | How the designer thinks it works | +| **User's model** | User | How the user thinks it works | +| **System image** | Product | What the product actually communicates | + +**Goal:** The user's model should match the design model; the system image is the only bridge. Matching models let users predict outcomes and recover from errors; mismatches breed confusion, self-blame, and support calls. + +**Example (thermostat):** design model — set a temperature, the system maintains it; common user model — higher setting heats faster (wrong), so users crank it to 90°F. + +**Build correct models with:** familiar metaphors (desktop, trash), visible system state, clear feedback, consistent behavior, progressive disclosure. + +See: [references/conceptual-models.md](references/conceptual-models.md) when the user's model diverges from how the product works. For fully worked teardowns (door handles, thermostats, digital products), see [references/case-studies.md](references/case-studies.md). + +## Human Error + +**Norman's key insight: there is no such thing as "human error" — only bad design.** When someone errs, look for the design flaw, not the person's flaw. + +### Types of Errors + +**Slips** — correct intention, wrong action: + +| Slip Type | Cause | Example | Design Fix | +|-----------|-------|---------|------------| +| **Action slip** | Wrong action on right target | Click "Delete" instead of "Edit" | Separate destructive actions | +| **Memory lapse** | Forget step in sequence | Forget attachment after writing "attached" | Gmail's attachment reminder | +| **Mode error** | Right action, wrong mode | Type in caps lock | Show mode state clearly | +| **Capture error** | Habit overrides intention | Drive to old office on autopilot | Interrupt at decision points | + +**Mistakes** — wrong intention, executed correctly: + +| Mistake Type | Cause | Example | Design Fix | +|-------------|-------|---------|------------| +| **Rule-based** | Apply wrong rule | Use formula for wrong situation | Provide context, confirm | +| **Knowledge-based** | Incomplete/wrong mental model | Misunderstand how system works | Better conceptual model | +| **Memory lapse** | Forget goal or plan | Forget why you opened the fridge | Reminders, history | + +### Design for Error + +**Prevent:** constraints that make errors impossible, undo/redo everywhere, confirmation for destructive actions, sensible defaults, forgiving input. +**Recover:** clear error messages, never erase the user's work, partial saves, easy reset to a known good state. + +**Error message checklist:** +- [ ] Says what went wrong (in human language) +- [ ] Says how to fix it +- [ ] Doesn't blame the user +- [ ] Preserves user's work +- [ ] Provides alternative path + +See: [references/human-error.md](references/human-error.md) for error prevention patterns. + +## The Seven Stages of Action + +**Norman's model for how humans interact with products:** + +``` +1. GOAL → "I want to adjust the temperature" +2. PLAN → "I'll use the thermostat" +3. SPECIFY → "I'll press the up arrow" +4. PERFORM → (presses button) + ─── Gulf of Execution ─── +5. PERCEIVE → (sees display change) +6. INTERPRET → "The number went up" +7. COMPARE → "Is this what I wanted?" + ─── Gulf of Evaluation ─── +``` + +**Design implications:** support stages 1-3 with signifiers, mappings, and constraints; stage 4 with good affordances; stages 5-7 with feedback and visible state. Walk any interaction through each stage to find where users get stuck. + +See: [references/seven-stages.md](references/seven-stages.md) for stage-by-stage analysis. + +## Human-Centered Design (HCD) Process + +``` +Observation → Idea Generation → Prototyping → Testing → (iterate) +``` + +Two specifics that change how you run this loop: in **Observation**, don't ask users what they want (they don't know) — watch for workarounds and frustrations in real contexts. In **Testing**, use real users not designers — 5 reveal ~85% of problems, so observe behavior over opinions and iterate. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|------| +| **No signifiers** | Users can't find features | Add visual cues for every interactive element | +| **No feedback** | Users don't know if action worked | Respond to every action within 0.1s | +| **Blaming users** | Ignores design flaws | Look for design cause of every "user error" | +| **Feature creep** | Complexity overwhelms | Apply constraints, progressive disclosure | +| **Inconsistency** | Breaks conceptual model | Same action = same result everywhere | +| **Ignoring context** | Designed for ideal conditions | Observe real usage environments | + +## Quick Diagnostic + +Audit any design: + +| Question | If No | Action | +|----------|-------|--------| +| Can users figure out what to do? | Poor discoverability | Add signifiers, improve affordances | +| Do users understand what happened? | Gulf of evaluation too wide | Add feedback, show system state | +| Can users recover from errors? | No error tolerance | Add undo, confirmation, clear messages | +| Does the control layout match the output? | Poor mapping | Reorganize controls to match spatial layout | +| Are impossible/irrelevant options hidden? | Missing constraints | Disable, hide, or remove invalid options | + +## Further Reading + +For the complete framework: + +- [*"The Design of Everyday Things"*](https://www.amazon.com/Design-Everyday-Things-Revised-Expanded/dp/0465050654?tag=wondelai00-20) by Don Norman (Revised & Expanded Edition, 2013) +- [*"Emotional Design"*](https://www.amazon.com/Emotional-Design-Love-Everyday-Things/dp/0465051367?tag=wondelai00-20) by Don Norman (design and emotion) + +## About the Author + +**Don Norman, PhD** is co-founder of the Nielsen Norman Group, director of The Design Lab at UC San Diego, and a former VP of Advanced Technology at Apple, where he coined the term "user experience." *The Design of Everyday Things* (1988, revised 2013) is widely considered the most influential design book ever written and is required reading in design programs worldwide. diff --git a/.agents/skills/design-everyday-things/references/affordances.md b/.agents/skills/design-everyday-things/references/affordances.md new file mode 100644 index 00000000..013be99e --- /dev/null +++ b/.agents/skills/design-everyday-things/references/affordances.md @@ -0,0 +1,259 @@ +# Affordances: Designing for Action + +An affordance is a relationship between an object and a person that determines how the object could possibly be used. A chair affords sitting. A handle affords pulling. A button affords pressing. Affordances exist in the physical properties of the object relative to the capabilities of the user, whether or not the user perceives them. The central design challenge is making affordances visible and unmistakable. + +## Affordance Types + +| Type | Definition | Key Characteristic | Example | +|------|------------|-------------------|---------| +| **Real affordance** | An action the object genuinely supports | Exists in the physics/code | A physical button can be pressed; a text input accepts keystrokes | +| **Perceived affordance** | An action the user believes is possible | Exists in the user's mind | A raised, shadowed rectangle looks pressable even if it is decorative | +| **Hidden affordance** | An action that exists but is not visible | Discoverable only by accident or instruction | Right-click context menus, multi-finger trackpad gestures | +| **False affordance** | An appearance of action that does not exist | Misleads the user | Underlined blue text that is not a link; a card with a shadow that is not clickable | +| **Anti-affordance** | A deliberate prevention of action | Communicates "you cannot do this" | A grayed-out disabled button; a railing that prevents falling | + +### The Critical Distinction + +Real affordances are properties of the system. Perceived affordances are properties of the user's interpretation. Good design aligns these two: every real affordance should be perceived, and no false affordance should exist. + +--- + +## Digital Affordance Patterns + +### Buttons + +| Property | Affords | Signal | +|----------|---------|--------| +| Raised appearance / shadow | Pressing / clicking | Drop shadow, gradient, border | +| Color contrast with background | Attention and interaction | Primary color, high contrast | +| Hover state change | "I respond to interaction" | Background darkens, cursor changes | +| Active/pressed state | "Your click registered" | Slight depression, color shift | +| Disabled state (grayed) | "Not available right now" | Reduced opacity, no cursor change | + +### Links + +| Property | Affords | Signal | +|----------|---------|--------| +| Color differentiation | Navigation | Blue or brand-accent color | +| Underline | "I am clickable text" | Text decoration underline | +| Cursor change to pointer | "Click me" | CSS cursor: pointer | +| Visited state color | "You have been here" | Purple or muted color | + +### Text Inputs + +| Property | Affords | Signal | +|----------|---------|--------| +| Border / outline | "Type here" | Visible rectangular boundary | +| Placeholder text | "This is what goes here" | Light gray sample text | +| Focus ring | "You are editing this" | Blue outline on focus | +| Blinking cursor | "I am ready for input" | Text insertion cursor | +| Label above/beside | "This field is for X" | Descriptive text | + +### Sliders + +| Property | Affords | Signal | +|----------|---------|--------| +| Handle / thumb | Dragging | Circular or rectangular grab target | +| Track | Range of movement | Horizontal or vertical line | +| Fill color | Current value | Colored portion of the track | +| Min/max labels | Boundaries | Text or numbers at each end | + +### Drag Targets + +| Property | Affords | Signal | +|----------|---------|--------| +| Grip dots or lines | "Grab and move me" | Six-dot handle icon | +| Cursor change to grab | "Draggable" | CSS cursor: grab | +| Lift animation on drag start | "I am being moved" | Shadow increase, slight scale up | +| Drop zone highlight | "Drop it here" | Border change, background tint | + +--- + +## Physical vs. Digital Affordances + +| Dimension | Physical | Digital | +|-----------|----------|---------| +| **Perception** | Seen, felt, heard directly | Seen on screen; no physical texture | +| **Constraint** | Physics prevents wrong use | Only code prevents wrong use | +| **Discoverability** | Explore by touch and manipulation | Explore by clicking, hovering, scrolling | +| **Feedback** | Immediate tactile response | Must be programmed explicitly | +| **Cultural learning** | Handles, knobs, buttons are universal | UI conventions are learned (hamburger menu, swipe gestures) | +| **Cost of error** | May cause physical harm | Rarely dangerous, but data loss possible | + +### Implications for Digital Design + +Physical objects get affordances "for free" from their material properties. Digital interfaces must manufacture every affordance through visual design. This means: + +1. Every interactive element needs deliberate visual treatment. +2. Non-interactive elements must be visually distinct from interactive ones. +3. New interaction patterns (gestures, voice) start with zero perceived affordance and need onboarding. + +--- + +## The Flat Design Problem: When Affordances Disappear + +Flat design (the removal of skeuomorphic visual cues like shadows, gradients, and borders) creates a systematic affordance crisis. When buttons look like labels and labels look like buttons, users cannot distinguish interactive elements from static content. + +### What Flat Design Removes + +| Removed Cue | Affordance Lost | User Impact | +|-------------|----------------|-------------| +| Drop shadows on buttons | "This is pressable" | Users do not recognize buttons | +| Borders on inputs | "Type here" | Users do not know where to click to type | +| Underlines on links | "This navigates" | Users cannot find links in body text | +| Gradients and bevels | "This is interactive" | All elements look equally flat and static | +| Visual depth / layering | "This is above/below that" | Users lose sense of hierarchy | + +### Recovering Affordances in Flat Design + +- Use **color contrast** to distinguish interactive elements from static ones. +- Add **hover and focus states** that reveal interactivity. +- Use **consistent spacing** to create clickable regions. +- Apply **subtle shadows or borders** (flat design does not mean zero visual depth). +- Always provide **cursor changes** on interactive elements. +- Pair **icons with labels** so meaning is not ambiguous. + +--- + +## Touch vs. Mouse Affordances + +| Factor | Mouse | Touch | +|--------|-------|-------| +| **Hover state** | Available and essential | Does not exist; cannot preview interactivity | +| **Precision** | High (single pixel) | Low (finger covers ~44px) | +| **Right-click** | Common interaction | Not available natively | +| **Drag and drop** | Natural with mouse | Conflicts with scroll gesture | +| **Cursor feedback** | Changes shape to signal affordance | No cursor exists | +| **Target size** | Minimum ~24px | Minimum 44x44px (Apple HIG) or 48x48dp (Material) | + +### Touch-Specific Affordance Strategies + +- Make all touch targets at least 44x44 points. +- Use visual weight (size, color, shadow) instead of hover states to signal interactivity. +- Provide haptic feedback (vibration) on interaction to replace the tactile click of a mouse button. +- Avoid relying on gestures as the only way to access critical actions; always provide a visible alternative. +- Show visual hints for swipeable content (partial next-card visible, dots indicator). + +--- + +## Affordance Audit Checklist + +Use this checklist to evaluate any screen or physical product. + +### Interactive Elements + +- [ ] Every button is visually distinguishable from non-interactive text and containers. +- [ ] Every link has at least two signals (color + underline, or color + cursor change). +- [ ] Every text input has a visible boundary (border, background contrast, or underline). +- [ ] Every slider has a visible handle and track. +- [ ] Every draggable element has a grip indicator. +- [ ] All touch targets are at least 44x44 points (mobile) or 24x24 pixels (desktop). + +### Non-Interactive Elements + +- [ ] Static text does not use the same color as links. +- [ ] Decorative images do not have clickable appearance (no pointer cursor, no hover effect). +- [ ] Section headers are not styled like buttons. +- [ ] Cards and containers that are not clickable do not have hover lift effects. + +### Hidden Affordances + +- [ ] Any gesture-based interaction also has a visible control alternative. +- [ ] Keyboard shortcuts are documented in the interface (tooltip, menu, help). +- [ ] Right-click menus duplicate functionality available through visible controls. +- [ ] Swipeable content shows a visual hint that more content exists. + +### False Affordances + +- [ ] No underlined text that is not a link. +- [ ] No colored text that looks like a link but is not. +- [ ] No card shadows or hover effects on non-interactive containers. +- [ ] No cursor: pointer on non-interactive elements. + +--- + +## Before/After Examples of Affordance Improvements + +### Example 1: Flat Submit Button + +**Before**: A gray text label "Submit" with no border, no shadow, no background color. Users do not realize it is clickable. + +**After**: A filled blue rectangle with white text "Submit", a subtle shadow, and a darkened hover state. Users immediately recognize it as a button. + +**Principle applied**: Perceived affordance aligned with real affordance through visual treatment. + +### Example 2: Hidden Navigation + +**Before**: A three-line hamburger icon in the top corner. New users do not know it contains navigation. Engagement with secondary pages is low. + +**After**: A visible horizontal navigation bar with text labels for the top 4 sections, plus a "More" dropdown for the rest. Engagement with secondary pages increases by 50% or more. + +**Principle applied**: Hidden affordance converted to visible affordance. + +### Example 3: Non-Obvious Text Input + +**Before**: A thin bottom-border line with a small floating label. Users click randomly around the area unsure where the input field actually is. + +**After**: A fully bordered rectangle with a label above, placeholder text inside, and a clear focus ring. Users click into the input immediately. + +**Principle applied**: Real affordance made perceivable through boundary signifiers. + +### Example 4: Gesture-Only Delete + +**Before**: On mobile, the only way to delete a list item is to swipe left. Users who do not know the gesture cannot delete items. + +**After**: Swipe-to-delete still works, but each item also has a visible trash icon on tap or a long-press menu. All users can access the delete function. + +**Principle applied**: Hidden affordance supplemented with visible alternative. + +--- + +## Common Affordance Failures by Platform + +### Web + +| Failure | Impact | Fix | +|---------|--------|-----| +| Ghost buttons (transparent with thin border) | Low click-through rates | Use filled buttons for primary actions | +| Cards without hover state that are clickable | Users miss clickable content | Add hover elevation or background change | +| Dropdown triggers that look like labels | Users do not know to click | Add a chevron icon and border | + +### Mobile (iOS / Android) + +| Failure | Impact | Fix | +|---------|--------|-----| +| Small touch targets | Frequent mis-taps, frustration | Minimum 44pt / 48dp targets | +| Swipe-only actions | Core functionality is invisible | Provide visible button alternative | +| Bottom sheet handle with no label | Users do not know to drag up | Add "Swipe up for details" text or an upward chevron | + +### Desktop Applications + +| Failure | Impact | Fix | +|---------|--------|-----| +| Toolbar with icon-only buttons | Users memorize slowly, new users lost | Add text labels below icons | +| Resizable panels without grab edges | Users cannot resize | Show a dotted grab edge or resize cursor on hover | +| Menu items with no keyboard shortcut listed | Power users cannot accelerate | Show shortcut text next to every menu item | + +--- + +## Accessibility and Affordances + +Affordances must work for all users, including those who use assistive technologies. + +| User Group | Affordance Consideration | +|-----------|------------------------| +| **Screen reader users** | Every interactive element must have an accessible role (button, link, input) and a descriptive label. Visual affordances are invisible; semantic affordances must replace them. | +| **Keyboard-only users** | Every interactive element must be focusable and operable with Enter or Space. Focus rings are the keyboard equivalent of hover states: they are affordance signifiers. | +| **Low-vision users** | Interactive elements need sufficient color contrast (WCAG 4.5:1 for text, 3:1 for UI components). Size thresholds increase. | +| **Motor-impaired users** | Touch targets must be larger (WCAG recommends 44x44 CSS pixels). Drag-and-drop must have a click-based alternative. | +| **Cognitive disabilities** | Affordances must be explicit, not implied. Labels are better than icons alone. Consistent placement is essential. | + +### Accessibility Affordance Checklist + +- [ ] All interactive elements have correct ARIA roles or native HTML semantics. +- [ ] Focus order follows visual order. +- [ ] Focus rings are visible and high-contrast. +- [ ] Interactive elements are reachable and operable via keyboard. +- [ ] Color is not the only affordance signal (shape, border, or icon accompanies color). +- [ ] Touch targets meet minimum size requirements. +- [ ] Drag interactions have non-drag alternatives. diff --git a/.agents/skills/design-everyday-things/references/case-studies.md b/.agents/skills/design-everyday-things/references/case-studies.md new file mode 100644 index 00000000..dbe8bd53 --- /dev/null +++ b/.agents/skills/design-everyday-things/references/case-studies.md @@ -0,0 +1,311 @@ +# Case Studies: Design Analysis Using Norman's Principles + +This collection of case studies applies Don Norman's design principles to real products, both physical and digital. Each case follows the same structure: the product, the design problem, the principle violated, a detailed analysis, the fix, and the broader lesson. These cases demonstrate that the same small set of principles explains why products are intuitive or infuriating. + +## Table of Contents +1. [Case Study 1: The Norman Door](#case-study-1-the-norman-door) +2. [Case Study 2: The Thermostat Mental Model](#case-study-2-the-thermostat-mental-model) +3. [Case Study 3: Stovetop Burner Mapping](#case-study-3-stovetop-burner-mapping) +4. [Case Study 4: Airplane Cockpit Mode Errors](#case-study-4-airplane-cockpit-mode-errors) +5. [Case Study 5: Hospital Medication Errors](#case-study-5-hospital-medication-errors) +6. [Case Study 6: ATM Interface Evolution](#case-study-6-atm-interface-evolution) +7. [Case Study 7: Smartphone Unlock Evolution](#case-study-7-smartphone-unlock-evolution) +8. [Case Study 8: Smart Home Light Controls](#case-study-8-smart-home-light-controls) +9. [Cross-Cutting Patterns: What Makes Designs Intuitive vs. Confusing](#cross-cutting-patterns-what-makes-designs-intuitive-vs-confusing) + +--- + +## Case Study 1: The Norman Door + +### Product + +Commercial building doors with flat push-plates on both sides, or handles on a door that requires pushing. + +### Design Problem + +People push when they should pull, and pull when they should push. This happens millions of times daily in buildings around the world. The problem is so pervasive that doors requiring a "Push" or "Pull" sign have become known as "Norman Doors." + +### Principles Violated + +**Affordances**, **Signifiers**, **Constraints** + +### Analysis + +A flat plate affords pushing. A handle affords pulling (and pushing, but the grip shape invites pulling). When a door has a handle on the side that requires pushing, the affordance (graspable handle) contradicts the required action (push). The user perceives a pull affordance, attempts to pull, fails, and then pushes. The "Push" sign is a signifier band-aid for a broken affordance. + +The deeper failure is a missing constraint. If the door only opens one way, the hardware should make the wrong action impossible. A flat plate on the push side and a handle on the pull side creates a physical constraint: you cannot pull a flat plate. + +### Fix + +- **Push side**: Flat plate (no handle). Affords only pushing. +- **Pull side**: Vertical handle. Affords pulling. +- **Automatic doors**: Eliminate the push/pull decision entirely. + +### Lesson + +When users consistently do the wrong thing, the design is wrong, not the users. The cheapest fix (a sign) is also the weakest. The best fix changes the physical design so the correct action is the only possible action. + +--- + +## Case Study 2: The Thermostat Mental Model + +### Product + +Home thermostats (traditional and digital). + +### Design Problem + +Users set the thermostat to an extreme temperature (90 degrees) believing it will heat the room faster. It does not. The heating system operates at a constant rate regardless of the target temperature. Setting it to 90 just means it runs longer, overshoots the comfortable temperature, and wastes energy. + +### Principle Violated + +**Conceptual Models** + +### Analysis + +Users apply a "valve" mental model: more = faster, like a faucet where turning the handle further produces more water flow. The thermostat actually works as a "goal-seeking" system: it turns heating on/off to reach and maintain a target temperature. The rate of heating is fixed. + +The system image fails because traditional thermostats show only the target number. They do not show the current temperature, the heating state (on/off), or the rate of change. Without this information, users cannot build the correct conceptual model. + +### Fix + +- Show current temperature AND target temperature side by side. +- Show "Heating to 72..." with an animated indicator. +- Show estimated time to reach target: "~15 minutes." +- Nest smart thermostats (like Nest) show all of this and learned the pattern early. + +### Lesson + +When users consistently misuse a product, the product's system image is failing to communicate its conceptual model. The fix is to make the internal mechanism visible, not to educate users through manuals. + +--- + +## Case Study 3: Stovetop Burner Mapping + +### Product + +Gas and electric stoves with four burners in a 2x2 grid and four control knobs in a 1x4 row. + +### Design Problem + +Users turn the wrong knob for the burner they want to use. They must look at labels (often small and hard to read) to determine which knob controls which burner because the linear arrangement of knobs does not correspond to the grid arrangement of burners. + +### Principle Violated + +**Mappings** + +### Analysis + +The four burners are arranged in a square: + +``` +[FL] [FR] +[BL] [BR] +``` + +The four knobs are arranged in a line: + +``` +[K1] [K2] [K3] [K4] +``` + +There is no natural spatial mapping between the linear knobs and the grid of burners. The relationship is arbitrary and must be memorized or read from a label. Even after years of use, many people occasionally turn the wrong knob. + +### Fix + +Arrange the knobs in a 2x2 grid matching the burner layout: + +``` +[FL] [FR] [KFL] [KFR] +[BL] [BR] [KBL] [KBR] +``` + +Or place each knob directly adjacent to its burner. Some modern stove designs use a staggered or offset knob layout that better matches the burner positions. + +### Lesson + +Natural spatial mapping eliminates the need for labels, memorization, and guesswork. When the control layout matches the output layout, the relationship is self-evident. + +--- + +## Case Study 4: Airplane Cockpit Mode Errors + +### Product + +Commercial aircraft autopilot and flight management systems. + +### Design Problem + +Pilots perform the correct action for the wrong mode, or fail to notice a mode change, leading to altitude deviations, speed errors, or in extreme cases, accidents. The 1994 Nagoya A300 crash and the 2009 Air France 447 disaster both involved mode confusion. + +### Principles Violated + +**Feedback**, **Signifiers**, **Conceptual Models** + +### Analysis + +Modern autopilot systems have dozens of modes: altitude hold, vertical speed, flight level change, approach, go-around, autothrottle, and many more. Mode transitions can be triggered by the pilot, by the automation, or by the system responding to conditions (e.g., reaching a target altitude). + +The problems are compounded: +1. **Mode annunciations are small**: A tiny text label on the Primary Flight Display changes from "ALT HOLD" to "V/S" but may not attract attention. +2. **Automation acts silently**: The system transitions modes without alerting the pilot. A critical mode change (like autothrottle disconnection) may be signaled by a brief tone that is missed in a noisy cockpit. +3. **Model complexity**: Pilots must maintain a mental model of multiple interacting automation modes. The combinations are too numerous to track reliably. + +### Fix + +- **Prominent mode annunciations**: Large, color-coded mode displays that change distinctly when the mode changes. +- **Mode change alerts**: Auditory and visual alerts when the automation changes mode, especially uncommanded changes. +- **Simplified mode structure**: Reduce the number of modes. Combine similar modes. Make transitions predictable. +- **Consistent behavior**: Same pilot action should produce the same result regardless of mode. + +### Lesson + +When systems have modes, those modes must be visible, and mode changes must be unmissable. The more modes a system has, the more likely users are to lose track of the current state. Simplify modes wherever possible, and make remaining modes impossible to overlook. + +--- + +## Case Study 5: Hospital Medication Errors + +### Product + +Electronic health record (EHR) systems and medication ordering interfaces. + +### Design Problem + +Physicians and nurses select the wrong medication, wrong dose, or wrong route of administration when ordering or administering medications. The Institute of Medicine estimates that medication errors harm at least 1.5 million Americans annually. + +### Principles Violated + +**Constraints**, **Signifiers**, **Feedback**, **Mappings** + +### Analysis + +Multiple design failures contribute: + +| Failure | Principle | Description | +|---------|-----------|-------------| +| Drug name confusion | Signifiers | "Hydroxyzine" vs. "Hydralazine" look similar in dropdown lists | +| Dose entry as free text | Constraints | No range validation; a tenfold error (1.0mg vs 10mg) is not caught | +| Units not locked | Constraints | User can type "mg" when "mcg" is required | +| Alert fatigue | Feedback | So many alerts fire that clinicians override 90%+ of them, including real dangers | +| Display density | Mappings | Medication lists show 50+ items in a flat list with no grouping or hierarchy | + +### Fix + +- **Tall Man Lettering**: hydrOXYzine vs. hydrALAzine (capitalize distinguishing letters). +- **Dose range validation**: Flag doses outside the normal range for the selected drug: "10mg is 10x the typical adult dose. Confirm or adjust." +- **Pre-set dose options**: Dropdown of standard doses for each drug instead of free-text entry. +- **Tiered alerts**: Reserve modal alerts for true contraindications. Use inline warnings for less critical issues. Reduce alert volume by 80% so the remaining alerts are respected. +- **Visual grouping**: Group medications by category (cardiac, analgesic, antibiotic) with visual separation. + +### Lesson + +In high-stakes environments, constraints are the most important design tool. Preventing errors is always better than detecting them. Alert fatigue is a failure of the feedback system: when everything is flagged as important, nothing is. + +--- + +## Case Study 6: ATM Interface Evolution + +**Product**: Automated teller machines (1980s to present). **Principles Violated** (early ATMs): Signifiers, Feedback, Conceptual Models, Mappings. + +Early ATMs had unlabeled buttons beside cryptic text screens. The mapping between button position and screen menu item was arbitrary and fragile. Users made frequent errors and needed staff assistance. + +| Era | Interface | Mapping | Feedback | Errors | +|-----|-----------|---------|----------|--------| +| 1980s | Unlabeled buttons + text menu | Arbitrary | Minimal; cryptic messages | High | +| 1990s | Labeled buttons + graphical menu | Improved (labels adjacent to items) | Better; clearer messages | Moderate | +| 2010s | Touchscreen | Direct (tap the option itself) | Good; progress bars, animations | Low | + +### Lesson + +Direct manipulation (touching the thing itself) produces the best mapping possible. ATM evolution is a 40-year demonstration of mapping improvement through progressively more natural interaction. + +--- + +## Case Study 7: Smartphone Unlock Evolution + +**Product**: Smartphone lock screens (2007 to present). **Principles Applied**: Affordances, Constraints, Feedback. + +Securing a device accessed 80-150 times daily requires balancing security against usability. Each generation reduced friction while maintaining or improving security. + +| Method | Era | Signifier | Feedback | Error Recovery | +|--------|-----|-----------|----------|---------------| +| **Slide to unlock** | 2007 | Arrow and track | Slider follows finger | Springs back on failure | +| **PIN** | 2007+ | Familiar keypad | Dots fill, shake on error | Escalating delays | +| **Pattern** | 2008+ | Grid of dots | Line follows finger | Shake, timeout | +| **Fingerprint** | 2013+ | Sensor position | Haptic pulse | Falls back to PIN | +| **Face unlock** | 2017+ | None (ambient) | Padlock icon animation | Falls back to PIN | + +### Lesson + +The best interface is no interface. Each evolution reduced the Gulf of Execution while keeping evaluation clear. As technology improves, constraints can be maintained while affordances become invisible. + +--- + +## Case Study 8: Smart Home Light Controls + +**Product**: Smart home lighting (Philips Hue, LIFX, smart switches, voice assistants). **Principles Violated**: Conceptual Models, Mappings, Affordances. + +A simple task (turn on the kitchen light) now involves choosing between a wall switch, app, voice command, hub, or automation. Users often cannot turn on their own lights because the conceptual model is fragmented. + +### Analysis + +| Problem | Principle | Description | +|---------|-----------|-------------| +| Wall switch kills smart bulb power | Conceptual model conflict | User's model: switch controls light. Reality: switch cuts power to the smart bulb, making it unresponsive to the app. | +| Multiple control points | Mapping confusion | The light can be controlled from 4+ places. Which one is "current"? | +| State ambiguity | Feedback failure | Is the light off because the switch is off, the app is off, the schedule turned it off, or the bulb has no power? | +| Voice command variability | Specification difficulty | "Turn on the kitchen light" vs "Turn on kitchen" vs "Lights on in the kitchen." Which works? | +| Automation surprises | Unexpected behavior | Lights turn on at 6 AM because of an automation the user forgot they set up. | + +### Fix + +- **Single source of truth**: All control methods feed into one system reflecting true state. +- **Switches send commands, not power**: Smart switches send commands to the hub rather than cutting electrical power to the bulb. +- **State always visible**: App and wall display always show current state. +- **Fallback to simple**: If the smart system fails, the physical switch still works. + +### Lesson + +Adding "smart" capabilities to simple products undermines the original simplicity. Every new control point must integrate with the existing model, not create a parallel one. + +--- + +## Cross-Cutting Patterns: What Makes Designs Intuitive vs. Confusing + +Across all eight case studies, the same patterns emerge repeatedly. + +### What Makes Designs Intuitive + +| Pattern | How It Works | Seen In | +|---------|-------------|---------| +| **Direct manipulation** | Act on the thing itself, not through an intermediary | Touchscreen ATM, smartphone unlock, WYSIWYG editors | +| **Spatial correspondence** | Control layout matches output layout | Stove fix, car seat adjusters, elevator buttons | +| **Visible system state** | Users always know what mode, state, or phase the system is in | Thermostat fix, airplane mode annunciation, smart home state | +| **Physical constraint** | Wrong action is impossible | Norman Door fix, USB-C, medication dose validation | +| **Immediate feedback** | Every action produces a perceivable result | Smartphone unlock haptics, ATM animations, inline validation | +| **Familiar metaphors** | New products map to known mental models | Trash can, folders, shopping cart | + +### What Makes Designs Confusing + +| Pattern | How It Fails | Seen In | +|---------|-------------|---------| +| **Hidden modes** | Users perform correct action in wrong mode | Airplane autopilot, caps lock, smart home automations | +| **Arbitrary mapping** | Controls have no logical connection to outcomes | Stove knobs, early ATM buttons, light switch panels | +| **Silent failures** | Errors produce no feedback | Form submissions, background sync, medication order processing | +| **Conflicting affordances** | Hardware suggests one action, system requires another | Norman Door, smart home wall switch | +| **Broken metaphors** | Product looks like something familiar but behaves differently | Thermostat as valve, cloud as physical location | +| **Alert fatigue** | Too many warnings cause all warnings to be ignored | Hospital medication alerts, confirmation dialogs | + +### The Universal Fix + +Every confusing design can be improved by asking six questions: + +1. **Can the user see what actions are possible?** (Affordances, Signifiers) +2. **Can the user tell which control affects which outcome?** (Mappings) +3. **Can the user avoid making errors?** (Constraints) +4. **Can the user see what happened?** (Feedback) +5. **Does the user understand how the system works?** (Conceptual Model) +6. **Can the user recover from mistakes?** (Error Tolerance) + +If the answer to any question is "no," the corresponding principle identifies both the problem and the category of solution. diff --git a/.agents/skills/design-everyday-things/references/conceptual-models.md b/.agents/skills/design-everyday-things/references/conceptual-models.md new file mode 100644 index 00000000..1f57b568 --- /dev/null +++ b/.agents/skills/design-everyday-things/references/conceptual-models.md @@ -0,0 +1,282 @@ +# Conceptual Models: How Users Think Products Work + +A conceptual model is a mental representation of how something works. Users form conceptual models of every product they interact with, whether or not the designer intended a particular model. When the user's model matches reality, the product feels intuitive. When it does not, the product feels broken. The designer's most important job is shaping the system image so that users build correct mental models. + +## The Three Models + +### Design Model + +The designer's understanding of how the product works. This model is complete and accurate because the designer built the system. + +### User's Model (Mental Model) + +The user's understanding of how the product works. This model is often incomplete, simplified, and sometimes wrong. Users build their model from the system image, not from documentation or training. + +### System Image + +Everything the product communicates to the user: its appearance, behavior, feedback, documentation, and responses. The system image is the only bridge between the design model and the user's model. + +### The Relationship + +``` +Designer ──creates──> Design Model + │ + shapes the + │ + v + System Image + │ + perceived by + │ + v +User ──builds──> User's Mental Model +``` + +**The gap problem**: Designers communicate with users only through the system image. If the system image is unclear, incomplete, or misleading, the user's model will diverge from the design model, and the product will feel confusing. + +### Why Models Matter + +| Alignment | User Experience | Example | +|-----------|----------------|---------| +| Models match | User predicts outcomes correctly, feels confident, recovers easily from mistakes | User understands that "Trash" holds deleted files temporarily and can restore them | +| Models partially match | User succeeds at basic tasks but fails at advanced ones | User can send email but does not understand threading or labels | +| Models mismatch | User is confused, frustrated, blames self, calls support | User cranks thermostat to 90 expecting faster heating | + +--- + +## Building Correct Conceptual Models + +### Principle 1: Make the System Visible + +Users cannot model what they cannot see. Make internal states, processes, and structures visible. + +| Strategy | Implementation | Example | +|----------|---------------|---------| +| Show system state | Persistent indicators | "Connected", "Syncing", "Offline" badge | +| Show structure | Visual hierarchy, navigation | Folder tree showing file organization | +| Show process | Step indicators, progress bars | "Step 2 of 4: Payment" | +| Show relationships | Visual grouping, connecting lines | Org chart, dependency diagram | +| Show history | Activity log, version history | "Last edited by Alice, 2 hours ago" | + +### Principle 2: Provide a Good Conceptual Framework + +Give users a simple, accurate model they can reason with. + +| Strategy | Implementation | Example | +|----------|---------------|---------| +| Use familiar metaphors | Map new concepts to known ones | Desktop, folders, trash can, shopping cart | +| Offer a simplified model first | Progressive complexity | Basic view with "Show advanced options" | +| Explain behavior, not mechanism | User-facing language | "Your file is stored safely in the cloud" not "Uploaded to S3 bucket us-east-1" | +| Be consistent | Same action always produces same result | Click always selects, double-click always opens | + +### Principle 3: Provide Feedback That Reinforces the Model + +Every interaction should confirm or refine the user's understanding. + +| Strategy | Implementation | Example | +|----------|---------------|---------| +| Show cause and effect | Animation connecting action to result | Dragged file animates into folder | +| Confirm expectations | Success messages that describe what happened | "Your message was sent to 3 recipients" | +| Correct misunderstandings | Helpful error messages | "This action will delete the original, not create a copy" | +| Reveal hidden states | Make the invisible visible | Show "Background sync in progress" instead of syncing silently | + +--- + +## Metaphor-Based Conceptual Models + +Metaphors are the most powerful tool for building conceptual models. They let users apply existing knowledge to new systems. + +### Classic Software Metaphors + +| Metaphor | Source Domain | What It Maps | What It Teaches | +|----------|-------------|-------------|----------------| +| **Desktop** | Office desk | Screen is a workspace | Organize items spatially, stack windows | +| **Folders** | Filing cabinet | Directory structure | Hierarchical organization, nesting | +| **Trash / Recycle Bin** | Physical waste bin | Deletion holding area | Deletion is two-phase: discard, then empty | +| **Shopping cart** | Physical shopping cart | Purchase collection | Gather items, then checkout all at once | +| **Inbox** | Physical mailbox | Message arrival point | New items arrive here, process and move them | +| **Clipboard** | Physical clipboard | Temporary storage | Copy puts it on the clipboard, paste retrieves it | +| **Bookmark** | Physical bookmark | Saved location | Mark a place to return to later | +| **Dashboard** | Car dashboard | Overview of key metrics | At-a-glance status of important indicators | + +### Why Metaphors Work + +1. **Transfer of knowledge**: Users already know how a physical shopping cart works. They apply that knowledge to the digital cart without instruction. +2. **Predictability**: If trash works like physical trash, users expect they can retrieve items before the bin is emptied. +3. **Vocabulary**: Metaphors provide a shared language. "Drag the file to the trash" is immediately understood. +4. **Constraints**: Metaphors imply constraints. A folder contains things. A trash bin is for discarding. + +--- + +## When Metaphors Break Down + +Every metaphor eventually reaches its limits. The digital domain does not perfectly mirror the physical domain, and extended metaphors can mislead users. + +| Metaphor | Where It Breaks | User Confusion | +|----------|----------------|---------------| +| **Desktop** | Unlimited windows, virtual desktops, no physical constraint | Users lose windows behind other windows | +| **Folders** | Files can exist in multiple locations (aliases, shortcuts, tags) | "I moved the file, why is it still in the other folder?" | +| **Trash** | Emptying trash is permanent; some systems auto-empty | "I emptied the trash, can I get it back?" | +| **Shopping cart** | Cart persists across sessions; items can sell out while in cart | "I had it in my cart yesterday, now it's gone" | +| **Save** | Auto-save means the floppy disk concept is obsolete | "Where's the save button?" (It auto-saves.) | +| **Cloud** | Implies floating, ephemeral; actually stored on physical servers | "Where exactly is my data?" | + +### Handling Metaphor Limits + +- **Acknowledge the limit explicitly**: "Unlike a physical folder, the same file can appear in multiple places." +- **Extend with new concepts**: Introduce "tags" as a complement to folders when hierarchical metaphor breaks down. +- **Provide escape hatches**: When the metaphor fails, provide a literal description. Show the actual file path alongside the metaphorical folder view. +- **Do not force the metaphor**: If the metaphor creates confusion, drop it and use direct interaction instead. + +--- + +## Model Mismatch Diagnosis + +When users struggle with a product, the cause is often a mismatch between their mental model and the system's actual behavior. Use this diagnostic process. + +### Step 1: Identify the Symptom + +| Symptom | Likely Mismatch | +|---------|----------------| +| User tries an action that does not exist | Their model includes capabilities the system lacks | +| User cannot find a feature that exists | Their model does not include the feature's location | +| User expects outcome A but gets outcome B | Their model predicts different behavior than the system delivers | +| User repeats an action unnecessarily | Their model does not include the system's automatic behavior (auto-save, sync) | +| User is afraid to act | Their model does not include recovery options (undo, trash) | + +### Step 2: Identify the User's Model + +Ask (or infer from behavior): +- "What did you expect to happen?" +- "Where did you look for this feature?" +- "How do you think [feature X] works?" + +### Step 3: Identify the Gap + +| Question | Analysis | +|----------|---------| +| Is the system image unclear? | The product does not communicate its behavior effectively | +| Is the metaphor misleading? | The metaphor sets wrong expectations | +| Is the model too complex? | The user simplified the model and lost critical detail | +| Is prior experience interfering? | The user applies a model from a different product | + +### Step 4: Fix the System Image + +| Gap Type | Fix Strategy | +|----------|-------------| +| Unclear system image | Add signifiers, feedback, state indicators | +| Misleading metaphor | Revise the metaphor, add explanatory text | +| Over-simplified model | Progressive disclosure: teach complexity gradually | +| Prior product interference | Onboarding that highlights "how we're different" | + +--- + +## Progressive Model Building: Simple to Complex + +Users should not need to understand the full system model before they can use it. Start with a simple model and reveal complexity as users need it. + +### Implementation Strategies + +| Strategy | How It Works | Example | +|----------|-------------|---------| +| **Beginner mode / Advanced mode** | Two views of the same system | Photo editor: basic adjustments vs. full curve controls | +| **Layered settings** | Common settings visible, advanced settings collapsed | "Show advanced options" expander | +| **Contextual education** | Teach concepts when the user first encounters them | Tooltip on first use: "Tags let you organize items without folders" | +| **Graduated onboarding** | Introduce features across multiple sessions | Day 1: core actions. Day 3: shortcuts. Day 7: advanced features. | +| **Inline help** | Brief explanations embedded in the interface | "?" icon next to complex settings, opening a brief explanation | + +### The Progression + +``` +Simple Model ──use──> Encounter Edge Case ──learn──> Richer Model ──use──> Mastery +``` + +- **Simple model**: "Delete moves items to Trash." +- **Edge case**: "I emptied the Trash. Can I get something back?" +- **Richer model**: "Trash is a 30-day holding period. After that, items are permanently removed. Premium users can recover items for 60 days." +- **Mastery**: The user understands the full lifecycle and plans accordingly. + +--- + +## Conceptual Model Evaluation Techniques + +### Technique 1: Draw-and-Explain + +Ask 5 users to draw how they think the system works (boxes, arrows, flow). Compare their drawings to the actual architecture. Where drawings diverge from reality, the system image is failing. + +### Technique 2: Prediction Test + +Before performing an action, ask the user: "What do you think will happen when you click this?" If their prediction is wrong, their model is wrong. Identify what led to the incorrect prediction. + +### Technique 3: Teaching Test + +Ask a user who has used the product for a week to explain it to a new user. Listen for: +- Inaccurate explanations (model is wrong). +- Missing concepts (model is incomplete). +- Hedging ("I think it works like... but I'm not sure") (model is uncertain). + +### Technique 4: Error Analysis + +Catalog the errors users make. Group them by the incorrect assumption that caused the error. Each assumption reveals a model mismatch. + +| Error | Incorrect Assumption | Model Fix | +|-------|---------------------|----------| +| User tries to drag files between cloud accounts | "My cloud drive works like a folder on my desktop" | Show account boundaries clearly | +| User types a URL in the search bar | "This text field is for navigating" | Differentiate search and address bar visually | +| User closes a tab expecting it to save | "Closing saves my work" | Auto-save, or prompt before closing unsaved work | + +--- + +## Conceptual Model Examples + +### The Thermostat + +- **Designer's model**: Set a target temperature. The system turns heating or cooling on/off to reach and maintain it. Setting a higher number does not make it heat faster. +- **Common user model**: The thermostat is a valve. Higher number = more heat output = faster warming. +- **System image failure**: Most thermostats show only the target number, not the rate of heating or the current mechanism (on/off). This allows the "valve" model to persist. +- **Fix**: Show current temperature AND target temperature. Show "Heating to 72..." with an animated indicator. Show estimated time to reach target. + +### The File System + +- **Designer's model**: Hierarchical tree structure. Files have a single location. Shortcuts/aliases point to files but are not copies. +- **Common user model**: "My documents are somewhere in the computer." Many users have no spatial model of file organization. +- **System image failure**: File explorers show the tree but do not teach the concept of hierarchy. Path bars are technical. Search bypasses the model entirely. +- **Fix**: Show breadcrumbs as a path. Animate navigation (zoom into folder). Show "You are here" in the tree. Use metaphor: "Like folders in a filing cabinet." + +### Version Control (Git) + +- **Designer's model**: A directed acyclic graph of snapshots with branches, merges, and remote references. +- **Common user model**: "Save" with the ability to go back. Maybe: "a timeline of saves." +- **System image failure**: Git's command-line interface exposes the full graph model with no simplification. Error messages reference concepts (detached HEAD, rebase, cherry-pick) that have no intuitive mapping. +- **Fix**: Visual branch diagrams, simplified workflows ("save point" instead of "commit"), and hiding advanced graph operations behind explicit expert mode. + +### Cloud Storage + +- **Designer's model**: Files stored on remote servers, synchronized across devices with conflict resolution. +- **Common user model**: "My files are in the cloud" (vague). Some users: "The cloud IS my computer's folder." +- **System image failure**: Sync status is often hidden. Conflict resolution happens silently or with cryptic duplicate filenames. +- **Fix**: Show sync status per file (synced, syncing, conflict). Explain conflicts in plain language: "This file was edited on two devices. Which version do you want to keep?" + +--- + +## Teaching Users Correct Models Through Design + +### Do Not Rely on Documentation + +Users do not read manuals, help pages, or knowledge bases before using a product. The product itself must teach its model. + +### Techniques for In-Product Education + +| Technique | When to Use | Example | +|-----------|-------------|---------| +| **Onboarding tour** | First-time use | Highlight key areas, explain core concepts in 3-5 steps | +| **Empty states** | No content yet | "You have no projects yet. Create one to get started." with illustration showing the concept | +| **Inline hints** | First encounter with a feature | "Tip: Drag columns to reorder them" shown once, then dismissed | +| **Animated transitions** | State changes | File animates from inbox to archive, teaching the user where it went | +| **Consistent patterns** | Everywhere | When every list behaves the same way, users generalize from one to all | +| **Error messages as teaching** | On mistakes | "You cannot delete a folder that contains files. Move or delete the files first." teaches hierarchy | +| **Progressive disclosure** | Complexity management | Show basic model first, reveal advanced model on demand | + +### The Golden Rule of Model Teaching + +**Show, do not tell.** An animation of a file moving to the trash teaches more than a paragraph of text explaining deletion. An inline preview of formatting teaches more than a formatting guide. Let users experience the model through interaction. diff --git a/.agents/skills/design-everyday-things/references/constraints.md b/.agents/skills/design-everyday-things/references/constraints.md new file mode 100644 index 00000000..d03e42ad --- /dev/null +++ b/.agents/skills/design-everyday-things/references/constraints.md @@ -0,0 +1,256 @@ +# Constraints: Limiting Actions to Prevent Errors + +Constraints are design elements that limit the possible actions a user can take. Used well, they make errors impossible or improbable. The underlying principle is simple: instead of telling users what not to do, make the wrong action physically, logically, or semantically impossible. Every constraint added is one fewer error the user can make. + +## Four Constraint Types + +### Physical Constraints + +Physical constraints use shape, size, or material properties to restrict actions. + +| Constraint | How It Works | Example | +|-----------|-------------|---------| +| Shape exclusion | Parts only fit one way | USB-A plug has a correct orientation; USB-C fits both ways | +| Size limitation | Object is too large/small for wrong use | A large plug cannot fit a small socket | +| Material resistance | Force required prevents accidental activation | Childproof medicine bottle requires push-and-twist | +| Barrier | Physical blockage prevents access | Guardrails prevent cars from leaving the road | + +**Digital equivalent**: Input masks, character limits, file type restrictions, and minimum/maximum values. + +### Cultural Constraints + +Cultural constraints rely on shared social conventions and learned norms to guide behavior. + +| Constraint | How It Works | Example | +|-----------|-------------|---------| +| Social norms | Expected behavior in context | Whispering in a library, facing forward in an elevator | +| Color conventions | Shared color meanings | Red for stop/danger, green for go/safe | +| Positional conventions | Expected placement of elements | OK/Cancel button order (platform-dependent) | +| Interaction conventions | Learned digital behaviors | Double-click to open, single-click to select | + +**Design implication**: Cultural constraints are powerful but invisible. Violating them causes confusion even when the system technically works. + +### Semantic Constraints + +Semantic constraints use the meaning of a situation to limit the set of possible actions. + +| Constraint | How It Works | Example | +|-----------|-------------|---------| +| Contextual meaning | Meaning restricts logical placement | A rearview mirror only makes sense facing the rear | +| Role meaning | Knowledge of purpose limits actions | A windshield is obviously not a door | +| Temporal meaning | Timing restricts when actions make sense | Cannot review an order before adding items | + +**Digital equivalent**: Contextual menus that show only relevant actions, conditional fields that appear based on prior selections. + +### Logical Constraints + +Logical constraints use reasoning to limit what is possible through exclusion. + +| Constraint | How It Works | Example | +|-----------|-------------|---------| +| Process of elimination | Only one option remains | Last puzzle piece can only go in the remaining hole | +| Mutual exclusion | Choosing A makes B impossible | Radio buttons: selecting one deselects others | +| Dependency chains | Step B requires step A | Cannot format text before selecting it | +| Completeness check | All parts must be present | Form cannot submit until all required fields are filled | + +--- + +## Digital Constraint Implementations + +### Input Validation as Constraint + +| Validation Type | What It Constrains | Implementation | +|----------------|-------------------|----------------| +| **Type restriction** | Only numbers, only letters, specific format | `input type="email"`, `type="tel"`, regex patterns | +| **Range restriction** | Minimum and maximum values | `min="0" max="100"`, date ranges, slider bounds | +| **Length restriction** | Character count | `maxlength="280"`, with visible counter | +| **Format restriction** | Specific pattern required | Input mask for phone: (___) ___-____ | +| **Enum restriction** | Only predefined options allowed | Dropdown, radio buttons, autocomplete with fixed list | +| **Real-time validation** | Invalid input rejected as typed | Inline error showing before form submission | + +### Best Practices for Input Validation + +- Prefer prevention over detection: use a date picker instead of validating a typed date. +- Validate in real time, not only on submit. Show inline feedback as the user types. +- When rejecting input, explain what is expected: "Phone number must be 10 digits" not "Invalid input." +- Accept flexible formats and normalize internally: "1234567890", "(123) 456-7890", and "123-456-7890" should all be accepted for a phone number. + +### Progressive Disclosure as Constraint + +Progressive disclosure constrains what users see and interact with, reducing cognitive load and preventing premature actions. + +| Pattern | What It Constrains | Example | +|---------|-------------------|---------| +| **Collapsed sections** | Hides advanced options until requested | "Advanced settings" expandable panel | +| **Wizard / stepper** | Shows only current step | Multi-step checkout flow | +| **Conditional fields** | Shows fields only when relevant | "Other" text field appears only when "Other" is selected | +| **Role-based visibility** | Shows features based on permissions | Admin panel visible only to admin users | +| **Contextual menus** | Shows only actions relevant to the selected item | Right-click menu changes based on element type | + +### Disabled States and Forced Sequences + +Disabled states constrain users by making actions visually present but temporarily unavailable. + +| Pattern | When to Use | How to Implement | +|---------|------------|-----------------| +| **Disabled button** | Required precondition not met | Gray out button, add tooltip explaining why | +| **Locked wizard step** | Prior steps incomplete | Show step indicator but prevent skipping ahead | +| **Conditional enable** | Depends on another field's value | Enable "Confirm" only after checkbox is checked | +| **Time-gated action** | Action requires waiting period | "You can send again in 30 seconds" with countdown | +| **Auth-gated action** | Requires login or elevated permissions | Show the action but redirect to login on click | + +**Critical rule for disabled states**: Always explain why the action is disabled. A disabled button with no explanation is a constraint that creates frustration rather than guiding users. + +| Implementation | User Experience | +|---------------|----------------| +| Disabled button, no explanation | "Why can't I click this? Is it broken?" | +| Disabled button with tooltip | "I see -- I need to fill in the required fields first." | +| Disabled button with inline helper text | "Fill in all required fields to enable submission." | + +### Undo/Redo as Error Recovery Constraint + +Undo/redo does not prevent errors, but it constrains the impact of errors by making them reversible. + +| Pattern | Implementation | Example | +|---------|---------------|---------| +| **Immediate undo** | Toast notification with "Undo" link | Gmail "Message sent. Undo" | +| **Action history** | List of recent actions with rollback | Google Docs version history | +| **Soft delete** | Items move to trash, not permanently deleted | Recycle bin, 30-day retention | +| **Autosave with versions** | Every change is saved and reversible | Google Docs, Figma auto-save | +| **Confirmation dialog** | "Are you sure?" before destructive action | Delete account confirmation | + +### When to Use Confirmation Dialogs + +Confirmation dialogs are appropriate only for: +- **Irreversible** actions (delete account, send broadcast email) +- **High-consequence** actions (charge credit card, publish to production) +- **Unusual** actions (something the user does rarely and might have triggered accidentally) + +They are NOT appropriate for: +- Routine actions (saving a document, closing a tab) +- Actions that are easily reversible (moving an item, changing a setting) +- Frequent operations (every dialog slows the user down and trains them to click "OK" without reading) + +--- + +## Constraint Design Patterns by Use Case + +### E-Commerce Checkout + +| Constraint | Type | Purpose | +|-----------|------|---------| +| Cannot proceed to payment without shipping address | Logical (forced sequence) | Prevents incomplete orders | +| Credit card field accepts only digits with auto-formatting | Physical (input mask) | Prevents format errors | +| "Place Order" disabled until terms checkbox is checked | Logical (dependency) | Ensures legal compliance | +| Quantity selector with min=1, max=99 | Physical (range) | Prevents zero or absurd quantities | +| Address autocomplete from verified database | Semantic (constrained options) | Prevents undeliverable addresses | + +### User Registration + +| Constraint | Type | Purpose | +|-----------|------|---------| +| Password strength meter with minimum requirements | Physical (validation) | Prevents weak passwords | +| Email format validation | Physical (format) | Prevents invalid email addresses | +| Username uniqueness check (real-time) | Logical (exclusion) | Prevents duplicate accounts | +| Age gate with date picker | Semantic (contextual) | Prevents underage registration | +| CAPTCHA before submission | Cultural (convention) + Logical | Prevents automated abuse | + +### Content Management + +| Constraint | Type | Purpose | +|-----------|------|---------| +| Draft / Published / Archived states with transitions | Logical (forced sequence) | Content must be reviewed before publishing | +| Character limits on titles and descriptions | Physical (length) | Prevents layout-breaking content | +| Image upload restricted to specific formats and sizes | Physical (type + size) | Prevents unsupported media | +| Scheduled publish date must be in the future | Semantic (temporal) | Prevents backdated publishing | +| Role-based editing permissions | Cultural (authority) + Logical | Prevents unauthorized changes | + +--- + +## When Constraints Help vs. Frustrate + +### Constraints That Help + +| Scenario | Why It Helps | +|----------|-------------| +| Date picker instead of free text | Users cannot enter an invalid date format | +| Disabled "Next" until required fields are complete | Users cannot skip required information | +| Autocomplete for city/state from zip code | Reduces typing and prevents mismatched data | +| File upload limit with clear message | Prevents timeout errors on oversized files | +| Character counter approaching limit | Users adjust their content proactively | + +### Constraints That Frustrate + +| Scenario | Why It Frustrates | +|----------|------------------| +| Password rules that are excessively complex | Users cannot create a memorable password | +| Dropdown with 200+ country options | Slower than typing; users scroll endlessly | +| Forced sequence when steps are independent | Users cannot fill in information in their preferred order | +| Preventing paste into a "confirm email" field | Users must retype, increasing error rate | +| Requiring phone number when it is not needed | Users feel the product is collecting unnecessary data | + +### The Constraint Spectrum + +``` +Too few constraints Just right Too many constraints + | | | + Error-prone Error-free, smooth Frustrating, slow + Confusing Guided Patronizing + Flexible Efficient Rigid +``` + +The goal is the middle zone: enough constraints to prevent errors, not so many that users feel restricted. + +--- + +## Anti-Patterns: Over-Constraining Users + +| Anti-Pattern | Problem | Better Approach | +|-------------|---------|----------------| +| **Preventing copy-paste in forms** | Increases errors by forcing manual re-entry | Allow paste; validate the result | +| **Session timeouts without warning** | Users lose work without notice | Warn before timeout, offer extension | +| **Forced password change every 90 days** | Users choose weaker passwords to cope | Monitor for breaches instead | +| **Maximum line length in text fields** | Users cannot write naturally | Use soft limits with warnings, not hard limits | +| **Blocking form submission for non-critical warnings** | Users cannot proceed despite having correct intent | Distinguish errors (block) from warnings (allow with note) | +| **Requiring all fields when most are optional** | Users abandon the form | Mark truly required fields; make the rest optional | + +--- + +## Constraint Audit Checklist + +### Error Prevention + +- [ ] All form inputs have appropriate type constraints (number fields accept only numbers, etc.). +- [ ] Date and time inputs use pickers rather than free-text fields. +- [ ] Required fields are clearly marked and enforced before submission. +- [ ] Actions that depend on preconditions are disabled (with explanation) until preconditions are met. +- [ ] Destructive actions require confirmation or offer undo. + +### Input Quality + +- [ ] Input masks or autocomplete are used for structured data (phone, postal code, credit card). +- [ ] Range constraints are enforced with clear min/max indicators. +- [ ] Real-time validation provides feedback as the user types. +- [ ] Error messages explain what is expected, not just what is wrong. + +### Sequence and Flow + +- [ ] Multi-step processes enforce logical order when necessary. +- [ ] Independent steps can be completed in any order. +- [ ] The current step and remaining steps are visible. +- [ ] Users can go back to previous steps without losing data. + +### Recovery + +- [ ] Undo is available for all non-destructive actions. +- [ ] Soft delete (trash/archive) is used instead of permanent deletion. +- [ ] Autosave prevents data loss. +- [ ] Session recovery restores unsaved work after timeout or crash. + +### Appropriateness + +- [ ] No constraint exists purely for the system's convenience at the user's expense. +- [ ] Constraints match the severity of the potential error. +- [ ] Users are not forced to provide information that is not necessary for the task. +- [ ] Paste is allowed in all text fields. +- [ ] Flexible input formats are accepted and normalized (phone numbers, dates). diff --git a/.agents/skills/design-everyday-things/references/feedback.md b/.agents/skills/design-everyday-things/references/feedback.md new file mode 100644 index 00000000..c4677476 --- /dev/null +++ b/.agents/skills/design-everyday-things/references/feedback.md @@ -0,0 +1,283 @@ +# Feedback: Communicating Results Back to the User + +Feedback is the information a system sends back to the user after an action. Without feedback, users operate in the dark: they cannot tell whether their action registered, whether it succeeded, or what state the system is in. The absence of feedback is one of the most common and damaging design failures. Every action a user takes must produce a perceivable response. + +## Feedback Types + +### Visual Feedback + +The most common and versatile feedback channel. Visual feedback works for nearly all interactions because users are already looking at the interface. + +| Pattern | When to Use | Example | +|---------|------------|---------| +| Color change | State transitions, validation | Button turns green on success, field border turns red on error | +| Animation | Object manipulation, transitions | Item slides off screen when deleted, card flips when toggled | +| Icon change | Status updates, toggle states | Bookmark icon fills in when activated, checkbox gets a checkmark | +| Text update | Confirmations, counts, values | "3 items selected", "Saved at 2:30 PM" | +| Position change | Drag-and-drop, reordering | Item moves to its new position in the list | +| Opacity change | Enable/disable, focus shift | Background dims when a modal opens | + +### Auditory Feedback + +Sound provides feedback without requiring the user to look at the screen. Useful for confirmations, alerts, and background processes. + +| Pattern | When to Use | Example | +|---------|------------|---------| +| Confirmation tone | Action completed successfully | macOS "whoosh" on sent email | +| Error sound | Something went wrong | System alert sound on invalid action | +| Notification chime | New information available | Chat message received sound | +| Typing clicks | Keystroke registration (mobile) | Keyboard tap sounds on iOS | +| Progress tone | Background process advancing | Scanning/processing sound | + +**Caution**: Always provide a way to mute sounds. Never rely on sound as the only feedback channel (accessibility requirement). Sound should supplement visual feedback, not replace it. + +### Haptic Feedback + +Vibration and force feedback on touch devices provide physical confirmation of actions. + +| Pattern | When to Use | Example | +|---------|------------|---------| +| Tap confirmation | Button press registered | Short vibration on keypress | +| Selection feedback | Item selected or toggled | Subtle haptic pulse on toggle | +| Error feedback | Action failed or invalid | Sharp double-vibration on error | +| Boundary feedback | Reached end of scrollable content | Rubber-band haptic at scroll edge | +| Success feedback | Major action completed | Strong single pulse on "Order Placed" | + +### Progress Feedback + +Communicates advancement toward completion during longer operations. + +| Pattern | When to Use | Duration Context | +|---------|------------|-----------------| +| Determinate progress bar | Duration is known/estimable | File upload, multi-step process | +| Indeterminate spinner | Duration is unknown | Network request, search | +| Skeleton screen | Content is loading | Page or section load | +| Percentage text | Precise progress matters | "Uploading: 67% complete" | +| Step indicator | Multi-phase process | "Step 2 of 4: Payment" | +| Elapsed time counter | Very long operations | "Processing... 3m 22s elapsed" | + +--- + +## Response Time Guidelines + +These thresholds, established by usability research (Miller 1968, Card et al. 1983, Nielsen 1993), define user expectations for system response. + +| Threshold | User Perception | Required Feedback | +|:---------:|----------------|-------------------| +| **0 - 100ms** | Instantaneous. Action feels directly connected to result. | Direct visual change (color, position, state). No loading indicator needed. | +| **100ms - 1s** | Noticeable delay. Still feels responsive but the system is "thinking." | Show cursor change or subtle animation. No spinner needed yet. | +| **1s - 10s** | Significant delay. User's attention begins to wander. | Show spinner or progress indicator. Keep the user informed that work is happening. | +| **10s - 60s** | Long wait. User may switch tasks. | Show progress bar with percentage or estimated time. Allow the operation to continue in the background. | +| **> 60s** | Very long wait. User may assume failure. | Show progress, elapsed time, and estimated remaining time. Send a notification when complete. Allow the user to navigate away. | + +### Response Time by Interaction Type + +| Interaction | Expected Response Time | Feedback Strategy | +|-------------|:---------------------:|-------------------| +| Button click | < 100ms | Instant visual state change | +| Form field validation | < 300ms after typing stops | Inline validation message | +| Page navigation | < 1s | Skeleton screen or loading bar | +| Search results | < 2s | Skeleton screen with animated placeholder | +| File upload (small) | 1-5s | Progress bar | +| File upload (large) | 5-60s+ | Progress bar with percentage and cancel button | +| Data export | 10s-5min | Background process with notification on completion | +| Account creation | < 3s | Full-screen success state | + +--- + +## Feedback Patterns by Interaction Type + +### Click / Tap Feedback + +| State | Visual Feedback | Purpose | +|-------|----------------|---------| +| Hover | Background color change, cursor change | "This is interactive" | +| Active (pressed) | Darker color, slight scale-down | "Your click registered" | +| Loading | Spinner replaces label, or button shows loading state | "Processing your request" | +| Success | Checkmark icon, color change to green, or toast message | "Action completed" | +| Error | Shake animation, red color, or inline error message | "Something went wrong" | + +### Form Submission Feedback + +| Stage | Feedback | Implementation | +|-------|----------|---------------| +| Validation (inline) | Green checkmark or red error per field | Show as user completes each field | +| Submission initiated | Button shows loading state, form inputs disabled | Prevent duplicate submissions | +| Success | Toast notification, redirect, or inline success message | "Your changes have been saved" | +| Partial success | Yellow warning with details | "Saved, but 2 fields need attention" | +| Failure | Inline errors at fields, summary at top, form data preserved | Never erase user input on error | + +### Drag and Drop Feedback + +| Stage | Feedback | Purpose | +|-------|----------|---------| +| Drag start | Element lifts (shadow increase), ghost follows cursor | "You are holding this" | +| Drag over valid target | Drop zone highlights (border, background) | "You can drop here" | +| Drag over invalid target | No highlight, or red border, cursor shows "not-allowed" | "You cannot drop here" | +| Drop | Element animates to new position, drop zone returns to normal | "Placed successfully" | +| Cancel (drop outside) | Element animates back to original position | "Action cancelled, nothing changed" | + +### Loading State Patterns + +| Pattern | Best For | Description | +|---------|----------|-------------| +| **Spinner** | Unknown duration, small area | Rotating circle or dots. Simple but uninformative. | +| **Skeleton screen** | Page or section loads | Gray placeholder shapes matching content layout. Feels faster than a spinner. | +| **Progress bar (determinate)** | Known duration | Fills from left to right. Best when you can calculate progress. | +| **Progress bar (indeterminate)** | Unknown duration, larger area | Bar animates back and forth. Better than spinner for larger regions. | +| **Percentage text** | Long operations | "43% complete" gives precise expectation. | +| **Shimmer effect** | Content cards, lists | Gradient animation flowing across placeholder shapes. | + +### Error Feedback + +| Principle | Implementation | +|-----------|---------------| +| Say what went wrong | "Your password must be at least 8 characters" not "Invalid input" | +| Say how to fix it | "Add 3 more characters to your password" | +| Do not blame the user | "That email address is not registered" not "You entered a wrong email" | +| Preserve user's work | Never clear a form on error. Show errors inline and let users fix them. | +| Use appropriate severity | Red and bold for blocking errors. Yellow for warnings. Gray for hints. | +| Place errors near the source | Inline errors below the relevant field. Summary at the top for multiple errors. | + +### Error Message Template + +``` +[Icon] [What happened] +[Why it happened - optional, if it helps] +[How to fix it] +[Alternative action - optional] +``` + +**Example**: +``` +[!] We could not process your payment. +Your card was declined by the issuing bank. +Please try a different card or contact your bank. +[Try a different payment method] +``` + +### Success Feedback + +| Pattern | When to Use | Example | +|---------|------------|---------| +| **Toast notification** | Non-critical confirmations | "Settings saved" (auto-dismiss after 4s) | +| **Inline success message** | Form submissions | Green banner: "Your profile has been updated" | +| **Full-screen celebration** | Major milestones | Confetti animation on completing onboarding | +| **Redirect with flash** | After creating something | Redirect to the new item with a "Created successfully" banner | +| **Subtle state change** | Toggle/minor actions | Star icon fills in, count increments | +| **Email/notification** | Background processes | "Your export is ready" email with download link | + +--- + +## Too Much vs. Too Little Feedback + +### Too Little Feedback + +| Symptom | User Impact | Fix | +|---------|-------------|-----| +| Click produces no visible change | User clicks again, causing duplicates | Add immediate visual state change on click | +| Form submits with no confirmation | User resubmits, or navigates away unsure | Show success toast or redirect to confirmation | +| Background save with no indicator | User manually saves repeatedly | Show "Saved" indicator with timestamp | +| Error fails silently | User believes action succeeded | Always show errors explicitly | +| Long process with no progress | User assumes system is frozen | Show progress indicator for any operation > 1 second | + +### Too Much Feedback + +| Symptom | User Impact | Fix | +|---------|-------------|-----| +| Alert dialog for every action | User develops "dialog blindness" and clicks OK without reading | Use toasts for non-critical feedback, reserve dialogs for critical confirmations | +| Sound on every click | Annoying, especially in shared spaces | Use sound sparingly, only for important events | +| Animation on every state change | Interface feels hyperactive and distracting | Limit animation to meaningful transitions | +| Multiple notification channels for one event | Email + push + in-app + SMS overwhelms | Let users choose notification channels | +| Confirmation toast that blocks content | User must dismiss it before continuing | Use non-blocking toast that auto-dismisses | + +### The Feedback Balance Rule + +- Every action needs *some* feedback. +- Not every action needs *prominent* feedback. +- Match feedback prominence to action importance. + +| Action Importance | Feedback Prominence | +|:-----------------:|:-------------------:| +| Critical (delete account, payment) | Modal dialog, full-screen confirmation | +| Important (save, submit, send) | Toast notification, inline confirmation | +| Routine (click, select, toggle) | Subtle visual state change | +| Ambient (auto-save, sync) | Tiny indicator, no interruption | + +--- + +## Feedback in Accessibility Context + +| User Group | Requirements | +|-----------|-------------| +| **Screen reader** | ARIA live regions for dynamic updates; `role="alert"` for errors; progress announcements; focus moves to new messages | +| **Keyboard-only** | Visible focus rings; focus moves to resulting content after actions; loading states trap focus appropriately | +| **Low-vision** | Color paired with icon and text; animations paired with text messages; WCAG 4.5:1 contrast | +| **Motion-sensitive** | `prefers-reduced-motion` alternatives; no aggressive pulsing; avoid parallax and spinning | + +--- + +## Feedback Audit Checklist + +### Presence + +- [ ] Every clickable element has a visible response within 100ms. +- [ ] Every form submission produces explicit success or error feedback. +- [ ] Every operation longer than 1 second shows a loading indicator. +- [ ] Every error displays a human-readable message with remediation steps. +- [ ] State changes (toggle, selection, mode) produce visible feedback. + +### Timing + +- [ ] Direct manipulation feedback is under 100ms. +- [ ] Inline validation fires within 300ms after the user stops typing. +- [ ] Spinners appear within 1 second of starting a long operation. +- [ ] Toast messages auto-dismiss in 4-8 seconds (with a way to dismiss manually or keep visible). +- [ ] Background operations notify the user upon completion. + +### Appropriateness + +- [ ] Critical actions produce prominent feedback (modal, full-screen). +- [ ] Routine actions produce subtle feedback (state change, micro-animation). +- [ ] No unnecessary alert dialogs for routine confirmations. +- [ ] Sound feedback has a mute option. +- [ ] Feedback does not block the user's primary workflow. + +### Accessibility + +- [ ] ARIA live regions announce dynamic feedback for screen readers. +- [ ] Focus moves to error messages or success messages as appropriate. +- [ ] Color is not the only feedback channel (icons, text, borders also used). +- [ ] Animations have reduced-motion alternatives. +- [ ] Error messages identify which field has the problem. + +### Content + +- [ ] Error messages say what went wrong, why, and how to fix it. +- [ ] Success messages confirm what was done. +- [ ] Progress indicators show meaningful advancement (not just spinning). +- [ ] System state is visible at all times (connection status, save status, mode). + +--- + +## Examples of Excellent and Poor Feedback + +### Excellent: Gmail Undo Send + +After clicking Send, Gmail shows a toast: "Message sent. Undo." The toast persists for a configurable number of seconds. The user has visual confirmation (message sent) and an immediate recovery option (undo). Feedback and error recovery in a single, unobtrusive element. + +### Excellent: Stripe Payment Form + +As the user types a credit card number, the form identifies the card type (Visa, Mastercard) and displays the logo. Invalid digits are rejected in real-time. The expiration date auto-formats. Errors appear inline below each field. The submit button shows a spinner during processing and a checkmark on success. Every stage of the interaction has clear, immediate feedback. + +### Poor: Silent Form Submission + +A contact form has a "Submit" button. The user clicks it. Nothing happens for 3 seconds, then the page reloads and the form is empty. Did the message send? The user has no way to know. They may submit again, creating duplicates, or leave without confidence. + +### Poor: Aggressive Alert Dialogs + +An enterprise application shows an alert dialog for every action: "Are you sure you want to save?" "Save successful!" "Are you sure you want to navigate away?" Users click OK/Yes on every dialog without reading them, which means when a truly important confirmation appears (like permanent deletion), it is dismissed reflexively. + +### Poor: Invisible Background Sync + +A note-taking app syncs to the cloud in the background but provides no indicator. The user edits a note, closes the app, and opens it on another device expecting to see the changes. The sync had not completed. No feedback was ever given about sync status, so the user had no way to know. diff --git a/.agents/skills/design-everyday-things/references/human-error.md b/.agents/skills/design-everyday-things/references/human-error.md new file mode 100644 index 00000000..323ee1ca --- /dev/null +++ b/.agents/skills/design-everyday-things/references/human-error.md @@ -0,0 +1,288 @@ +# Human Error: Designing for Mistakes + +There is no such thing as human error. There is only bad design. When a person makes an error, the cause is almost always a design flaw: poor feedback, misleading signifiers, bad mappings, missing constraints, or a broken conceptual model. Blaming users for errors is the designer's greatest failure. Instead, design systems that prevent errors, tolerate errors, and make recovery easy. + +## Slips vs. Mistakes: The Fundamental Taxonomy + +Don Norman divides errors into two categories based on where the failure occurs in the action cycle. + +| | Slips | Mistakes | +|---|-------|---------| +| **Definition** | Correct intention, wrong action | Wrong intention, correctly executed | +| **Cause** | Attention failure, motor error, habit | Incorrect mental model, wrong rule, faulty reasoning | +| **Awareness** | User often notices immediately | User may not realize error until consequences appear | +| **Example** | Clicking "Delete" when reaching for "Edit" | Using the wrong formula in a spreadsheet because the user misunderstands the data | +| **Fix approach** | Make actions distinct and recoverable | Build correct conceptual models and provide better information | + +--- + +## Slip Types + +### Action-Based Slips + +The user intends to perform one action but accidentally performs a similar or adjacent one. + +| Subtype | Mechanism | Example | Design Prevention | +|---------|-----------|---------|-------------------| +| **Adjacent target** | Clicking the wrong button because it is too close | Tapping "Delete" instead of "Edit" on mobile | Separate destructive actions from constructive ones by distance and visual style | +| **Similar action** | Performing a habitual action instead of the intended one | Typing your old password after changing it | Provide clear feedback when the old credential is rejected and guide to the new one | +| **Description similarity** | Confusing two objects that look alike | Grabbing the wrong file from a list of similar names | Make distinguishing information prominent (dates, sizes, thumbnails) | + +### Memory-Lapse Slips + +The user forgets a step in a familiar sequence. + +| Subtype | Mechanism | Example | Design Prevention | +|---------|-----------|---------|-------------------| +| **Omitted step** | Skipping a step in a multi-step task | Forgetting to attach a file after writing "see attached" | Detect the omission (Gmail attachment reminder) | +| **Lost place** | Forgetting which step they are on | Returning to a form after an interruption and re-entering data | Persist form state; show progress indicators | +| **Forgotten intention** | Walking to a room and forgetting why | Opening a settings page and forgetting which setting to change | Provide search within settings; show recently changed items | + +### Mode Errors + +The user performs the correct action for one mode while the system is in a different mode. + +| Subtype | Mechanism | Example | Design Prevention | +|---------|-----------|---------|-------------------| +| **Invisible mode** | The current mode is not visually indicated | Typing in all caps because caps lock is on with no indicator | Always show the current mode visually (caps lock indicator, edit/view mode badge) | +| **Unexpected mode change** | The system changed modes without the user noticing | Airplane auto-throttle disengages silently | Announce mode changes with prominent feedback | +| **Cross-application mode** | Different behavior in different apps for the same action | Ctrl+S saves in one app, does something else in another | Follow platform conventions; never repurpose standard shortcuts | + +### Capture Errors + +A frequently performed action "captures" and overrides the intended less-frequent action. + +| Subtype | Mechanism | Example | Design Prevention | +|---------|-----------|---------|-------------------| +| **Habit capture** | Habitual sequence overrides intended deviation | Driving to old workplace instead of new one on autopilot | Insert interruptions at decision points in habitual sequences | +| **Routine capture** | A daily routine overrides a one-time variation | Opening email client instead of the report you intended to work on | Use reminders, task lists, and calendar blocks to interrupt routines | + +--- + +## Mistake Types + +### Rule-Based Mistakes + +The user applies a correct rule in the wrong situation, or applies a wrong rule that seems correct. + +| Subtype | Mechanism | Example | Design Prevention | +|---------|-----------|---------|-------------------| +| **Wrong rule** | Applying a rule from a different context | Using "Reply All" when only "Reply" was appropriate because the user follows a "always reply all" rule | Show recipient count prominently, warn on large recipient lists | +| **Misclassified situation** | Correctly following a rule, but for the wrong problem type | Using the standard password reset flow when the account is actually locked (different issue, different fix) | Diagnose the situation for the user before presenting solutions | +| **Outdated rule** | Following a rule that used to be correct | A nurse giving a medication dose based on an old protocol | Version and timestamp all rules, policies, and procedures visible in the interface | + +### Knowledge-Based Mistakes + +The user lacks the knowledge or has an incorrect mental model to handle a novel situation. + +| Subtype | Mechanism | Example | Design Prevention | +|---------|-----------|---------|-------------------| +| **Incomplete model** | The user's understanding of the system is partial | A user deletes a shared file not knowing it affects other users | Show sharing indicators and warn about impact | +| **Incorrect model** | The user's understanding is actively wrong | User believes setting thermostat to 90 heats the room faster | Redesign system image to teach correct model (show heating rate) | +| **Analogy failure** | Applying a model from one system to a different system | Expecting "undo" to work like a timeline when it actually works as a stack | Make the undo model explicit: show action history | + +### Memory-Lapse Mistakes + +The user forgets their goal, plan, or evaluation criteria. + +| Subtype | Mechanism | Example | Design Prevention | +|---------|-----------|---------|-------------------| +| **Forgotten goal** | Losing track of what they set out to do | Opening the phone to set a timer but getting distracted by notifications | Provide reminders: "You opened Settings. Looking for something?" | +| **Forgotten plan** | Losing track of multi-step plan | Forgetting the third item in a three-item to-do after completing the first two | Show task lists, checklists, and recently started workflows | +| **Forgotten evaluation** | Forgetting what "success" looks like | Adjusting a photo but forgetting the original state to compare against | Provide before/after toggle, history, or comparison view | + +--- + +## Error Prevention Strategies by Type + +### Preventing Slips + +| Strategy | Implementation | Prevents | +|----------|---------------|----------| +| **Increase target distance** | Separate destructive actions from routine actions by space and visual grouping | Adjacent target slips | +| **Distinctive appearance** | Make destructive buttons red, routine buttons blue | Description similarity slips | +| **Confirmation for irreversible actions** | "Delete this account? This cannot be undone." | Action slips with permanent consequences | +| **Mode indicators** | Always-visible badge showing current mode | Mode errors | +| **Interrupts at decision points** | "You're about to send to 500 people. Continue?" | Capture errors, memory-lapse slips | +| **Auto-detection** | Detect likely omissions and prompt | Memory-lapse slips (Gmail attachment warning) | +| **Constraints** | Disable invalid actions, enforce sequences | Multiple slip types | + +### Preventing Mistakes + +| Strategy | Implementation | Prevents | +|----------|---------------|----------| +| **Clear conceptual models** | Make system behavior visible and predictable | Knowledge-based mistakes | +| **Contextual information** | Show relevant data at the point of decision | Rule-based mistakes | +| **Undo and exploration** | Let users try things safely | Fear-based inaction (a form of mistake) | +| **Wizards and guides** | Step-by-step assistance for complex tasks | Knowledge-based and rule-based mistakes | +| **Default values** | Pre-fill with the most common or safest option | All mistake types | +| **Checklists** | Visible task lists for multi-step processes | Memory-lapse mistakes | +| **Comparisons** | Show before/after, show alternatives side-by-side | Forgotten-evaluation mistakes | + +--- + +## Error Recovery Patterns + +### Undo + +| Pattern | Scope | Implementation | +|---------|-------|---------------| +| **Single undo** | Most recent action | Ctrl+Z, "Undo" button | +| **Multi-level undo** | Multiple recent actions | Undo stack with history list | +| **Undo toast** | Time-limited reversal | "Action completed. Undo (5s)" | +| **Version history** | All changes over time | Named versions, autosave snapshots | +| **Soft delete** | Deletion recovery | Trash bin with 30-day retention | + +### Confirmation Dialogs + +Use confirmation dialogs sparingly and only for high-consequence, irreversible actions. + +| Effective Confirmation | Ineffective Confirmation | +|-----------------------|------------------------| +| "Delete 47 files permanently? This cannot be undone." | "Are you sure you want to save?" | +| "Send this email to 1,200 subscribers?" | "Are you sure you want to close this tab?" | +| "Downgrade your account? You will lose access to premium features." | "Are you sure you want to log out?" | + +**The confirmation dialog trap**: If you show confirmations for routine actions, users develop "dialog blindness" and click "Yes" without reading. Then the one time the confirmation matters, they click "Yes" again out of habit. + +### Autosave + +| Feature | Purpose | +|---------|---------| +| Continuous autosave | No work is ever lost due to crash, timeout, or accidental navigation | +| Visible save indicator | "All changes saved" or "Saving..." shows the user the system is working | +| Named save points | Users can create explicit save points for comparison | +| Conflict resolution | When two versions exist, show both and let the user choose | + +### Clear Error Messages + +**The error message formula**: + +``` +1. What happened (in plain language) +2. Why it happened (if helpful) +3. How to fix it (specific actionable steps) +4. Alternative path (if available) +``` + +**Good example**: +``` +We couldn't save your changes. +Your internet connection was interrupted. +Check your connection and try again, or download a copy of your work. +[Retry] [Download Copy] +``` + +**Bad example**: +``` +Error 500: Internal Server Error +``` + +--- + +## Error Message Design Checklist + +### Content + +- [ ] Message describes what happened in human language (no error codes as the primary message). +- [ ] Message explains how to fix the problem or what to try next. +- [ ] Message does not blame the user ("We couldn't process" not "You entered incorrectly"). +- [ ] Message provides an alternative path when possible. +- [ ] Technical details are available but not prominent (expandable section). + +### Presentation + +- [ ] Error appears near the source of the error (inline for form fields). +- [ ] Error is visually distinct (red border, error icon) but not alarming (avoid all-caps, exclamation marks). +- [ ] Error does not erase the user's work (form fields retain their values). +- [ ] Error is announced to screen readers (role="alert" or aria-live="assertive"). +- [ ] Error is persistent until the user fixes the issue (does not auto-dismiss). + +### Recovery + +- [ ] A clear action is provided (button, link, or instruction). +- [ ] The user can retry without re-entering information. +- [ ] If the error is systemic (server down), communicate expected resolution time. +- [ ] If the error requires support, provide a direct path to contact support with the error context pre-filled. + +--- + +## Designing for Error Tolerance + +Error-tolerant systems assume users will make errors and minimize their consequences. + +### Principles of Error Tolerance + +| Principle | Implementation | +|-----------|---------------| +| **Reversibility** | Every action can be undone. Deletion is soft. Edits are versioned. | +| **Low cost of experimentation** | Users can try things without fear. Preview modes, sandbox environments, and undo reduce the risk of exploration. | +| **Graduated consequences** | Minor actions have minor consequences. Major consequences require major confirmation. | +| **Data preservation** | The system never discards user data without explicit, confirmed intent. Form data survives errors, navigation, and session timeouts. | +| **Graceful degradation** | When something breaks, the system continues working at reduced capacity rather than failing completely. | + +--- + +## The Swiss Cheese Model of Errors + +James Reason's Swiss Cheese Model explains how errors lead to disasters. Each layer of defense has holes (like Swiss cheese). An error becomes a disaster only when the holes in multiple layers align and the error passes through all defenses. + +### Layers of Defense in Digital Products + +| Layer | Defense | Example | +|-------|---------|---------| +| **Layer 1: UI Constraints** | Prevent the action from being possible | Disabled button, input validation, type-safe inputs | +| **Layer 2: Warnings** | Alert the user before they proceed | "This will delete 47 files. Are you sure?" | +| **Layer 3: Immediate Feedback** | Show the result so the user can catch the error | File count changes, visual confirmation | +| **Layer 4: Undo / Reversal** | Allow the user to reverse the action | "Undo" toast, trash bin, version history | +| **Layer 5: Recovery** | Restore from backup or contact support | 30-day trash retention, admin recovery tools | + +For every critical action, ensure at least 3 layers of defense. If any single layer fails, the others catch the error. + +--- + +## Case Studies of Error-Prone Designs and Fixes + +| Case | Error | Root Cause | Fix | +|------|-------|-----------|-----| +| **Reply vs Reply All** | Private comment sent to entire organization | Buttons adjacent, identical, equally prominent | Make "Reply" default; show recipient count before sending | +| **Unsaved form on navigation** | User loses form data by clicking a link | No autosave, no navigation warning | Autosave to local storage; warn on navigation; restore on return | +| **Wrong file overwrite** | New file silently replaces existing file | No collision warning, no version history | Detect collision and warn; keep version history | +| **Medication dosage** | Nurse enters 10mg instead of 1.0mg | Free-text input, no range validation, small targets | Pre-set dose dropdown; range validation; large targets | + +--- + +## Error Audit Checklist + +### Prevention + +- [ ] Destructive actions are visually separated from routine actions. +- [ ] Destructive actions require confirmation (for irreversible actions only). +- [ ] Input constraints prevent invalid data entry (type, range, format). +- [ ] The system detects likely omissions and prompts the user (attachment reminders, required fields). +- [ ] Mode indicators are always visible when modes exist. +- [ ] Default values are set to the safest or most common option. + +### Detection + +- [ ] Every action produces visible feedback within 100ms. +- [ ] Error messages appear inline near the source of the error. +- [ ] Error messages describe what happened, why, and how to fix it. +- [ ] Error messages do not blame the user. +- [ ] System state is visible at all times (saved/unsaved, connected/disconnected). + +### Recovery + +- [ ] Undo is available for all non-destructive actions. +- [ ] Deleted items go to a recoverable trash/archive. +- [ ] Form data is preserved on error (fields are not cleared). +- [ ] Autosave prevents data loss from crashes and timeouts. +- [ ] Version history allows reverting to previous states. +- [ ] Session recovery restores work after accidental closure. + +### Systemic + +- [ ] Errors are logged and analyzed for design improvement (not user blame). +- [ ] The most common user errors are tracked and addressed in design iterations. +- [ ] New features are tested for common slip and mistake patterns before launch. +- [ ] Error rate is a tracked product metric alongside task completion and satisfaction. diff --git a/.agents/skills/design-everyday-things/references/mappings.md b/.agents/skills/design-everyday-things/references/mappings.md new file mode 100644 index 00000000..dc1da009 --- /dev/null +++ b/.agents/skills/design-everyday-things/references/mappings.md @@ -0,0 +1,263 @@ +# Mappings: Connecting Controls to Outcomes + +A mapping is the relationship between a control and its effect. When the mapping is natural, the connection between the two is obvious and immediate. When the mapping is arbitrary, users must memorize or guess which control does what. Natural mappings exploit spatial analogies, cultural conventions, and logical relationships to make products intuitive without instruction. + +## Natural Mapping Principles + +Natural mapping means the layout of the controls corresponds to the layout of the things being controlled. The best mappings require zero explanation. + +### The Spectrum of Mapping Quality + +| Quality | Characteristics | Learning Effort | Example | +|---------|----------------|-----------------|---------| +| **Natural / Direct** | Control IS the thing | None | Touchscreen: tap directly on the element to manipulate it | +| **Spatial analog** | Control layout mirrors output layout | Minimal | Car seat adjustment shaped like a miniature seat | +| **Cultural convention** | Learned but universally known | Low (one-time) | Red = stop, green = go | +| **Labeled arbitrary** | No inherent connection, but labeled | Moderate | Labeled switches on a panel | +| **Unlabeled arbitrary** | No inherent connection, no label | High (memorization) | Unmarked row of identical switches | + +--- + +## Spatial Mapping: Controls Match Layout of Output + +Spatial mapping is the most powerful type. When controls are arranged in the same physical pattern as the things they control, users do not need to think. + +### Principles + +1. **Layout correspondence**: If the controlled objects are arranged in a 2x2 grid, arrange the controls in a 2x2 grid. +2. **Direction correspondence**: Moving a control up should make something go up. Moving it right should make something go right. +3. **Proximity**: Each control should be physically close to the thing it affects. + +### Real-World Examples + +| Product | Spatial Mapping | Why It Works | +|---------|----------------|-------------| +| Car seat adjuster (Mercedes style) | A miniature seat shape that you tilt, slide, or raise | The control IS a spatial model of the seat | +| Elevator buttons arranged vertically | Higher button = higher floor | Spatial direction matches physical direction | +| Car side mirrors with a joystick | Push joystick left = mirror angles left | Direction of control matches direction of result | +| Crosswalk button facing the street it controls | Button faces the direction of the crosswalk | Proximity and orientation match | + +### Digital Spatial Mapping + +| Pattern | Spatial Relationship | Example | +|---------|---------------------|---------| +| Inline editing | Click on the content itself to edit it | Click a table cell to edit the value directly | +| WYSIWYG editors | What you see on screen matches the output | Document editors where formatting is visible | +| Drag-to-reorder | Move items to their new position directly | Drag a list item from position 3 to position 1 | +| Map controls | Pan the map by dragging the map itself | Google Maps, Figma canvas | +| Layout builders | Drag components to their spatial position | Website builders, dashboard editors | + +--- + +## Proximity Mapping: Controls Near What They Affect + +When a control is placed next to the thing it affects, the relationship is self-evident. + +### Principles + +1. **Adjacent placement**: The edit button should be next to the content it edits. +2. **Grouping**: Related controls should be grouped visually. +3. **Context menus**: Show actions in the context of the object they affect. + +### Digital Proximity Patterns + +| Pattern | Implementation | Benefit | +|---------|---------------|---------| +| Inline action buttons | Edit, delete, and copy icons appear on hover within each row | No ambiguity about which item the action affects | +| Contextual toolbars | Text formatting toolbar appears directly above selected text | Toolbar is clearly associated with the selection | +| Section-level controls | An "Add item" button at the bottom of the section it adds to | Users see where the new item will appear | +| Form-field validation | Error message appears directly below the field with the error | No confusion about which field is problematic | +| Tooltip/popover on element | Information appears next to the element that triggered it | Spatial proximity creates clear association | + +### Proximity Failures + +| Failure | Problem | Fix | +|---------|---------|-----| +| Global action bar far from content | Users cannot tell which content the actions apply to | Move actions inline or use clear selection indicators | +| Settings in a separate page | Users cannot see the effect of their changes | Show a live preview next to the settings | +| Error summary at the top of a form | Users must scroll to find the problematic field | Show errors inline at each field AND in a summary | + +--- + +## Cultural Mapping: Conventions and Expectations + +Cultural mappings are not inherently spatial or logical. They are learned conventions that most users in a culture share. + +### Common Cultural Conventions + +| Convention | Meaning | Scope | +|-----------|---------|-------| +| Red = danger / stop / error | Negative, cautionary | Near-universal | +| Green = safe / go / success | Positive, permissive | Near-universal | +| Left-to-right reading order | Sequence flows left to right | Western, many Asian | +| Right-to-left reading order | Sequence flows right to left | Arabic, Hebrew | +| Top-to-bottom = primary-to-secondary | Importance decreases downward | Most web conventions | +| X icon in top-right = close | Dismiss this window or dialog | Desktop and web | +| Floppy disk icon = save | Store the current state | Legacy but persistent | +| Shopping cart icon = purchase collection | Items selected for purchase | E-commerce | + +### When Cultural Conventions Conflict + +| Scenario | Conflict | Resolution | +|----------|----------|-----------| +| RTL vs LTR navigation arrows | "Forward" arrow points opposite directions | Flip arrow direction based on locale | +| Color meanings across cultures | Red means danger (West) vs. luck (East Asia) | Use icons and text alongside color | +| Date format | MM/DD/YYYY (US) vs DD/MM/YYYY (most of the world) | Use unambiguous format: "10 Feb 2024" or a date picker | +| Scroll direction | Natural scroll (Mac) vs. traditional scroll | Let users configure, but pick a default and commit | + +--- + +## Sequential Mapping: Order Matches Natural Flow + +Sequential mapping means the order of controls or steps matches the natural order of the task. + +### Principles + +1. **Temporal order**: Steps should be presented in the order they are performed. +2. **Reading order**: In LTR cultures, sequences should flow left-to-right or top-to-bottom. +3. **Dependency order**: Steps that depend on prior input should appear after that input. + +### Digital Sequential Mapping Patterns + +| Pattern | Implementation | Example | +|---------|---------------|---------| +| Multi-step wizard | Steps progress left-to-right in a stepper | Checkout: Shipping > Payment > Review > Confirm | +| Form field order | Fields ordered by task logic | Name > Email > Password > Confirm Password | +| Timeline / activity feed | Most recent at top, oldest at bottom (or reverse) | Consistent chronological direction | +| Breadcrumbs | Left-most is the root, right-most is the current page | Home > Category > Subcategory > Product | + +### Sequential Mapping Failures + +| Failure | Problem | Fix | +|---------|---------|-----| +| Address form: City before Street | Violates natural writing order | Reorder to match how people write addresses | +| Payment details before cart review | Users commit before seeing what they are paying for | Show cart summary before payment step | +| "Cancel" button before "Submit" | Reading order suggests cancel is the primary action | Place primary action (Submit) at the end of the reading flow | + +--- + +## Mapping Evaluation Framework + +Use this framework to evaluate the mapping quality of any control-to-outcome relationship. + +### Mapping Quality Scorecard + +| Criterion | Score (1-5) | Notes | +|-----------|:-----------:|-------| +| **Spatial correspondence**: Does the control layout mirror the output layout? | | | +| **Proximity**: Is the control near the thing it affects? | | | +| **Direction**: Does the direction of control movement match the direction of effect? | | | +| **Convention**: Does the mapping follow established cultural conventions? | | | +| **Sequence**: Do steps follow the natural task order? | | | +| **Labeling**: When mapping is not natural, are labels clear and complete? | | | +| **Consistency**: Are similar mappings used consistently throughout the product? | | | +| **Total (average)** | | | + +### Interpretation + +| Average Score | Quality | Action | +|:------------:|---------|--------| +| 4.5 - 5.0 | Excellent natural mapping | Maintain; minor refinements only | +| 3.5 - 4.4 | Good but learnable | Improve labels and proximity | +| 2.5 - 3.4 | Moderate; requires some learning | Redesign layout to improve spatial and sequential mapping | +| 1.0 - 2.4 | Poor; arbitrary mapping | Fundamental redesign required | + +--- + +## Classic Mapping Failures + +### The Stovetop Knob Problem + +**Setup**: Four burners arranged in a 2x2 grid. Four knobs arranged in a 1x4 row. + +**Problem**: Users cannot tell which knob controls which burner without reading labels, because the linear arrangement of knobs does not match the grid arrangement of burners. + +**Fix**: Arrange knobs in a 2x2 grid matching the burner layout, or place each knob directly adjacent to its burner. + +### The Light Switch Panel + +**Setup**: A row of 6 identical switches controlling lights in different parts of a room. + +**Problem**: No spatial correspondence between switch position and light position. Users flip switches randomly. + +**Fix**: Arrange switches on a floor plan diagram, or label each switch with the zone it controls, or use smart lighting with per-fixture controls. + +### The Elevator Button Panel + +**Setup**: Two columns of buttons for floors 1-20. + +**Problem**: Is floor 3 in the left column or the right column? Does the left column go up or does the right column? Convention varies between buildings. + +**Fix**: A single vertical column where higher buttons correspond to higher floors. Simple, unambiguous spatial mapping. + +### The Hotel Shower + +**Setup**: A single unmarked knob that controls both temperature and flow. + +**Problem**: Users cannot predict whether turning the knob will make the water hotter, colder, or change the pressure. The mapping of rotation direction to outcome is not signified. + +**Fix**: Separate temperature and flow controls. Mark hot and cold directions with color (red/blue) and use a consistent rotation convention. + +--- + +## Digital Mapping Patterns + +### Settings Panels + +| Pattern | Mapping Quality | Why | +|---------|:--------------:|-----| +| Settings grouped by feature, with live preview | High | Proximity to affected feature, immediate feedback | +| Alphabetical settings list | Low | No correspondence between position and function | +| Settings organized by user task | Medium-High | Sequential mapping aligned with task flow | +| Tabbed settings with icons | Medium | Grouping helps, but icon-only tabs can be ambiguous | + +### Form Layouts + +| Pattern | Mapping Quality | Why | +|---------|:--------------:|-----| +| Single column, top-to-bottom | High | Matches reading order and task sequence | +| Two-column with related fields side by side | Medium-High | Spatial grouping of related fields (First Name / Last Name) | +| Multi-column with unrelated fields | Low | Reading path is ambiguous (left-to-right then down? Or top-to-bottom then right?) | +| Accordion sections | Medium | Groups are clear, but hidden sections break spatial awareness | + +### Navigation + +| Pattern | Mapping Quality | Why | +|---------|:--------------:|-----| +| Tab bar with current tab highlighted | High | Position indicates section, highlight indicates current state | +| Sidebar matching page structure | High | Spatial hierarchy mirrors content hierarchy | +| Hamburger menu hiding all navigation | Low | No persistent spatial reference; user must open menu to see options | +| Breadcrumbs with clickable segments | High | Sequential mapping showing path from root to current page | + +--- + +## Mapping Improvement Exercises + +### Exercise 1: Map the Controls + +Choose a screen in your product. Draw two sketches: +1. The layout of the controls (buttons, inputs, toggles). +2. The layout of the things they affect (content areas, settings, outputs). + +Draw lines connecting each control to its effect. Ask: +- Do the lines cross? (If yes, the spatial mapping is poor.) +- Are the lines short? (Short lines = good proximity.) +- Does the spatial arrangement match? (Mirror layout = good spatial mapping.) + +### Exercise 2: The Label Removal Test + +Remove all labels from your interface mockup. Can a user still tell which control affects which element based on spatial position and proximity alone? Where the answer is no, the mapping depends on labels and could be improved with spatial redesign. + +### Exercise 3: Sequential Task Walkthrough + +List every step of a user task in chronological order. Now list the controls the user must interact with in the order they encounter them on screen. Do these two lists match? Where they diverge, the sequential mapping is broken. + +### Exercise 4: Convention Audit + +For each control-to-outcome mapping in your product, classify it as: +- **Spatial** (layout matches output) +- **Cultural** (follows a known convention) +- **Labeled** (arbitrary but clearly labeled) +- **Unlabeled arbitrary** (needs memorization) + +Any "unlabeled arbitrary" mapping is a design failure. Convert it to spatial, cultural, or at minimum labeled. diff --git a/.agents/skills/design-everyday-things/references/seven-stages.md b/.agents/skills/design-everyday-things/references/seven-stages.md new file mode 100644 index 00000000..108c0aa3 --- /dev/null +++ b/.agents/skills/design-everyday-things/references/seven-stages.md @@ -0,0 +1,316 @@ +# The Seven Stages of Action + +Don Norman's Seven Stages of Action is a model of how humans interact with products. Every interaction, from flipping a light switch to completing an online checkout, follows the same seven-stage cycle. Understanding these stages lets designers identify exactly where users get stuck and apply targeted fixes. The model divides neatly into two sides: execution (stages 1-4, bridging the Gulf of Execution) and evaluation (stages 5-7, bridging the Gulf of Evaluation). + + +## Table of Contents +1. [The Seven Stages in Detail](#the-seven-stages-in-detail) +2. [Stage 1: Goal Formation](#stage-1-goal-formation) +3. [Stage 2: Plan Formation](#stage-2-plan-formation) +4. [Stage 3: Specification of Action](#stage-3-specification-of-action) +5. [Stage 4: Execution (Perform)](#stage-4-execution-perform) +6. [Stage 5: Perception](#stage-5-perception) +7. [Stage 6: Interpretation](#stage-6-interpretation) +8. [Stage 7: Comparison](#stage-7-comparison) +9. [Using the Seven Stages as an Evaluation Tool](#using-the-seven-stages-as-an-evaluation-tool) +10. [Worked Examples](#worked-examples) +11. [Seven Stages Audit Worksheet](#seven-stages-audit-worksheet) + +--- + +## The Seven Stages in Detail + +``` + 1. GOAL + "What do I want?" + | + +-----------+-----------+ + | EXECUTION | EVALUATION + | | + 2. PLAN 7. COMPARE + "How can I do it?" "Is this what I wanted?" + | | + 3. SPECIFY 6. INTERPRET + "What specific action?" "What does this mean?" + | | + 4. PERFORM 5. PERCEIVE + "Do the action" "What happened?" + | | + +--- THE WORLD / SYSTEM + +``` + +--- + +## Stage 1: Goal Formation + +**Question the user asks**: "What do I want to accomplish?" + +The user forms a high-level intention. Goals can be precise ("Set the alarm for 7:00 AM") or vague ("Make this presentation look better"). + +### Where Users Get Stuck + +| Problem | Example | Design Cause | +|---------|---------|-------------| +| Goal is vague | "I want to fix this document" | The system does not help refine or clarify goals | +| Goal conflicts with system capabilities | "I want to merge these two accounts" (not supported) | Feature does not exist or is not discoverable | +| Goal is forgotten mid-task | User opens settings, forgets which setting they wanted | Complex navigation, many distractions | + +### Design Solutions for Stage 1 + +| Solution | Implementation | +|----------|---------------| +| **Suggest goals** | Home screen with common tasks: "Create a document", "Schedule a meeting" | +| **Make capabilities visible** | Dashboard showing all available features at a glance | +| **Support vague goals** | Search that accepts natural language: "make text bigger" | +| **Maintain goal context** | Show breadcrumbs, page titles, and task descriptions that remind users why they are here | + +--- + +## Stage 2: Plan Formation + +**Question the user asks**: "How can I do this? What approach should I take?" + +### Where Users Get Stuck + +| Problem | Example | Design Cause | +|---------|---------|-------------| +| No obvious path | "How do I share this?" (no share button visible) | Missing signifiers, hidden features | +| Multiple possible paths, unclear which is correct | "Should I use Export, Save As, or Download?" | Overlapping features with unclear distinctions | +| Plan requires knowledge the user lacks | "I need to configure the API webhook" (what is a webhook?) | Technical jargon, no progressive disclosure | + +### Design Solutions for Stage 2 + +| Solution | Implementation | +|----------|---------------| +| **Clear signifiers** | Visible labels for every available action | +| **Guided workflows** | Step-by-step wizards for complex tasks | +| **Reduce choices** | Offer the most common path prominently; hide alternatives | +| **Contextual help** | "How do I...?" link that opens task-specific guidance | +| **Templates and presets** | Pre-configured starting points that skip planning | + +--- + +## Stage 3: Specification of Action + +**Question the user asks**: "What specific action do I need to perform?" + +### Where Users Get Stuck + +| Problem | Example | Design Cause | +|---------|---------|-------------| +| Cannot find the control | "Where is the save button?" | Poor visual hierarchy, inconsistent placement | +| Cannot identify the correct control | "Is this the right dropdown?" | Ambiguous labels, icon-only controls | +| Action requires non-obvious sequence | "Click here, then hold Shift, then click there" | Complex interaction that is not signified | + +### Design Solutions for Stage 3 + +| Solution | Implementation | +|----------|---------------| +| **Consistent placement** | Primary actions always in the same location across screens | +| **Clear labels** | Every control has a text label (not just an icon) | +| **Affordances** | Interactive elements look interactive (buttons look clickable) | +| **Keyboard shortcuts visible** | Show shortcut in tooltip or menu alongside the action name | +| **Command palette** | Searchable list of all actions for users who know what they want | + +--- + +## Stage 4: Execution (Perform) + +**Question the user asks**: "I'm doing it. Is this working?" + +### Where Users Get Stuck + +| Problem | Example | Design Cause | +|---------|---------|-------------| +| Click does not register | Tap target too small on mobile | Touch target below 44pt minimum | +| Action is physically difficult | Precise drag-and-drop on a touchscreen | Interaction not optimized for input device | +| Accidental action | Tapping the wrong button because targets overlap | Insufficient spacing between targets | +| Action is slow or tedious | Selecting 50 items one by one | No bulk selection or "Select All" option | + +### Design Solutions for Stage 4 + +| Solution | Implementation | +|----------|---------------| +| **Adequate target sizes** | Minimum 44x44pt touch targets, 24x24px desktop | +| **Input optimization** | Match interaction to device (tap on mobile, click on desktop) | +| **Spacing** | Sufficient distance between interactive targets | +| **Shortcuts** | Bulk actions, keyboard shortcuts, gesture shortcuts | +| **Forgiveness** | Undo for accidental actions, confirmation for destructive ones | + +--- + +## Stage 5: Perception + +**Question the user asks**: "What happened? What changed?" + +### Where Users Get Stuck + +| Problem | Example | Design Cause | +|---------|---------|-------------| +| No visible change | Click a button and nothing happens | No feedback implemented | +| Change is too subtle | A small number changed in a corner of the screen | Low visual prominence of the feedback | +| Change is too fast | A toast message appeared and disappeared in 1 second | Insufficient display duration | +| Change is off-screen | The effect happened below the fold | No scroll-to or highlight behavior | + +### Design Solutions for Stage 5 + +| Solution | Implementation | +|----------|---------------| +| **Immediate feedback** | Every action produces visible response within 100ms | +| **Prominent changes** | Use animation, color, and position to draw attention to what changed | +| **Sufficient duration** | Toast messages visible for 4-8 seconds with manual dismiss option | +| **Scroll to change** | Automatically scroll to or highlight the part of the interface that changed | +| **Multi-channel feedback** | Combine visual + auditory + haptic for important events | + +--- + +## Stage 6: Interpretation + +**Question the user asks**: "What does this mean?" + +### Where Users Get Stuck + +| Problem | Example | Design Cause | +|---------|---------|-------------| +| Feedback is ambiguous | A number changed from 3 to 4 but user does not know what it represents | Unclear labels or missing context | +| Feedback uses jargon | "Error: ECONNREFUSED" | Technical language not translated to human language | +| Feedback is misleading | Green checkmark appears but the action actually failed partially | Incorrect or premature success signal | +| Multiple changes at once | Several parts of the screen update simultaneously | No visual hierarchy to guide attention | + +### Design Solutions for Stage 6 + +| Solution | Implementation | +|----------|---------------| +| **Plain language** | All feedback in human-readable terms with no jargon | +| **Context** | Include enough information to interpret the feedback ("3 items deleted" not just "Done") | +| **Accurate status** | Only show success when the action truly succeeded end-to-end | +| **Single focus** | Sequence changes or highlight the most important one | +| **Error explanations** | Describe what happened, why, and how to fix it | + +--- + +## Stage 7: Comparison + +**Question the user asks**: "Is this what I wanted? Did I achieve my goal?" + +The user compares the interpreted result against their original goal from Stage 1. + +### Where Users Get Stuck + +| Problem | Example | Design Cause | +|---------|---------|-------------| +| Cannot confirm goal was achieved | "Did my email actually send?" | No explicit confirmation | +| Goal partially achieved | Three of four settings were saved but one failed silently | Partial success not communicated | +| Unexpected side effects | "I changed my username but now my old links are broken" | Consequences not explained before action | +| Cannot compare before and after | "Did the color actually change?" | No reference point for comparison | + +### Design Solutions for Stage 7 + +| Solution | Implementation | +|----------|---------------| +| **Explicit confirmation** | "Your email has been sent to alice@example.com" | +| **Complete status reporting** | "3 of 4 settings saved. 'Display name' could not be updated because..." | +| **Consequence preview** | "Changing your username will break existing links. Continue?" | +| **Before/after comparison** | Toggle or side-by-side view showing previous and current state | +| **Summary screens** | After multi-step processes, show a summary of everything that was done | + +--- + +## Using the Seven Stages as an Evaluation Tool + +The Seven Stages of Action is one of the most practical evaluation tools available. For any user task, walk through each stage and ask: "What could go wrong here?" + +### Walkthrough Template + +For each task you want to evaluate, fill in this table. + +| Stage | Question | Current Design Support | Gap / Problem | Severity (H/M/L) | Proposed Fix | +|:-----:|----------|----------------------|--------------|:-----------------:|-------------| +| 1. Goal | Can the user form a clear goal? | | | | | +| 2. Plan | Can the user figure out an approach? | | | | | +| 3. Specify | Can the user identify the right control? | | | | | +| 4. Perform | Can the user execute the action easily? | | | | | +| 5. Perceive | Can the user see what happened? | | | | | +| 6. Interpret | Can the user understand what it means? | | | | | +| 7. Compare | Can the user confirm the goal was achieved? | | | | | + +Attempt the task as a new user. At each stage, note what supports and what hinders. Rate severity (H/M/L) and propose a fix. + +--- + +## Worked Examples + +### Example 1: Booking a Flight + +| Stage | User Experience | Design Analysis | +|:-----:|----------------|-----------------| +| 1. Goal | "I want to fly from New York to London on March 15" | Goal is clear and specific | +| 2. Plan | "I'll search for flights on this booking site" | Plan is straightforward | +| 3. Specify | User must find origin, destination, date, and passenger fields | Fields are labeled and use autocomplete for cities: good | +| 4. Perform | User types "New York", selects from dropdown, picks date from calendar | Autocomplete and date picker reduce errors: good | +| 5. Perceive | Search results appear below | Results load with skeleton screens: good | +| 6. Interpret | User sees prices, times, airlines, and stops | Information is well-organized but "1 stop" does not say where or how long: gap | +| 7. Compare | User compares results to find the best option | Sort and filter available, but no "best value" indicator: minor gap | + +**Key fixes**: Show layover details (city, duration) inline. Add a "Best value" tag for flights that balance price and convenience. + +### Example 2: Using a Thermostat + +| Stage | User Experience | Design Analysis | +|:-----:|----------------|-----------------| +| 1. Goal | "I want the room to be warmer" | Goal is vague: how much warmer? | +| 2. Plan | "I'll turn up the thermostat" | Simple plan | +| 3. Specify | User looks for the up arrow or dial | Control is visible: adequate | +| 4. Perform | User presses up repeatedly or turns dial to a high number | User sets to 85 hoping for faster heating: conceptual model failure | +| 5. Perceive | Display shows "85" | Number changed: perceived | +| 6. Interpret | User believes the house will now heat faster | Interpretation is wrong because the system image does not explain the on/off mechanism | +| 7. Compare | Room is not noticeably warmer after 5 minutes | User is frustrated, may turn it up further | + +**Key fixes**: Show current temperature AND target. Show "Heating..." indicator. Show estimated time to reach target. Explain that the heating rate is constant regardless of the target setting. + +### Example 3: Completing an E-Commerce Checkout + +| Stage | User Experience | Design Analysis | +|:-----:|----------------|-----------------| +| 1. Goal | "I want to buy this item" | Clear goal | +| 2. Plan | "I'll go through checkout" | User expects a standard flow | +| 3. Specify | User must find "Checkout" or "Buy Now" button | Button is prominent and well-labeled: good | +| 4. Perform | User clicks the button | Proceeds to checkout: good | +| 5. Perceive | Checkout page loads with shipping, payment, and review sections | Clear step indicator "Step 1 of 3": good | +| 6. Interpret | User understands they must fill in shipping first | Labels are clear, fields are ordered logically: good | +| 7. Compare | After placing order, user sees confirmation with order number and expected delivery date | Explicit confirmation with all details: excellent | + +**Key observation**: E-commerce checkout is one of the most optimized seven-stage flows because conversion directly impacts revenue. + +--- + +## Seven Stages Audit Worksheet + +Rate each stage 1-5 (1 = users consistently fail, 5 = zero friction). + +| Stage | Rating (1-5) | What Works | What Fails | Priority Fix | +|:-----:|:------------:|-----------|-----------|-------------| +| 1. Goal | | | | | +| 2. Plan | | | | | +| 3. Specify | | | | | +| 4. Perform | | | | | +| 5. Perceive | | | | | +| 6. Interpret | | | | | +| 7. Compare | | | | | + +### Summary + +- **Weakest stage**: ___ +- **Side with more issues**: Execution (stages 1-4) / Evaluation (stages 5-7) +- **Total issues found**: ___ +- **Top 3 fixes by impact**: + 1. ___ + 2. ___ + 3. ___ + +### Follow-Up Actions + +- [ ] Design and prototype fixes for top-priority issues +- [ ] Test with 3-5 users using a think-aloud protocol +- [ ] Re-score each stage after implementing fixes +- [ ] Track improvement in task completion rate and time diff --git a/.agents/skills/design-everyday-things/references/signifiers.md b/.agents/skills/design-everyday-things/references/signifiers.md new file mode 100644 index 00000000..1d325889 --- /dev/null +++ b/.agents/skills/design-everyday-things/references/signifiers.md @@ -0,0 +1,297 @@ +# Signifiers: Communicating Where and How to Act + +Signifiers are perceivable cues that tell people where to act and how to act. While affordances define what actions are possible, signifiers are what users actually rely on to discover and use those affordances. A door handle affords pulling, but the "Pull" label is the signifier. A button affords clicking, but its raised shape and color are the signifiers. In practice, signifiers matter more than affordances because they are what users actually see. + +## Signifier Types + +### Deliberate Signifiers + +Signals intentionally placed by the designer to communicate interaction possibilities. + +| Signifier | What It Communicates | Context | +|-----------|---------------------|---------| +| "Push" / "Pull" label on a door | Direction of action | Physical product | +| Placeholder text in an input field | What data to enter | Web and mobile forms | +| Tooltip on hover | Purpose of a control | Desktop applications | +| Chevron icon on a dropdown | "This expands" | Any UI | +| Plus icon on a button | "Add new item" | Any UI | +| Breadcrumb trail | "You are here, and you came from there" | Web navigation | +| Step indicator (1 of 4) | "This is a sequence; you are at step 1" | Multi-step flows | + +### Accidental Signifiers + +Signals not designed intentionally but used by people to guide their behavior. + +| Signifier | What It Communicates | Context | +|-----------|---------------------|---------| +| Worn path across a lawn | "People walk here" | Physical environment | +| Fingerprints on a touchscreen | "Touch this area" | Kiosks, shared tablets | +| Scratches around a keyhole | "The key goes here" | Physical locks | +| Browser back-button frequency | "Users get lost on this page" | Web analytics as accidental signifier for designers | +| Scroll position heatmaps | "Most people stop reading here" | Analytics informing design | + +### Social Signifiers + +Signals derived from observing other people's behavior. + +| Signifier | What It Communicates | Context | +|-----------|---------------------|---------| +| A queue of people | "This is where you line up" | Physical spaces | +| Star ratings and review counts | "Other people chose this and rated it" | E-commerce, app stores | +| "1,204 people are viewing this" | "This is popular, act quickly" | Booking websites | +| Comment count on a post | "This sparked discussion" | Social media | +| "Trending" or "Popular" badges | "Many users are engaging with this" | Content platforms | +| Typing indicator in chat | "The other person is composing a response" | Messaging apps | + +--- + +## Digital Signifier Catalog + +### Cursor Changes + +| Cursor | Signifier Meaning | CSS Value | +|--------|------------------|-----------| +| Arrow | Default, non-interactive area | `default` | +| Pointer (hand) | Clickable element | `pointer` | +| Text beam | Text is selectable or editable | `text` | +| Grab (open hand) | Element is draggable | `grab` | +| Grabbing (closed hand) | Element is being dragged | `grabbing` | +| Resize arrows | Edge or corner is resizable | `ew-resize`, `ns-resize`, `nwse-resize` | +| Wait / spinner | System is processing | `wait` | +| Not-allowed | Action is unavailable | `not-allowed` | +| Crosshair | Precision selection area | `crosshair` | + +### Hover States + +| Pattern | What It Signals | Best For | +|---------|----------------|----------| +| Background color change | "This entire area is interactive" | Cards, list items, table rows | +| Underline appearance | "This text is a link" | Inline text links | +| Shadow elevation increase | "This element lifts up when interactive" | Cards, buttons | +| Border color change | "This container responds to interaction" | Input fields, selection areas | +| Opacity change | "This element is interactive" | Icons, images, secondary actions | +| Scale transform (slight) | "This element is alive" | Thumbnails, avatar images | + +### Placeholder Text and Labels + +| Signifier Element | Purpose | Best Practice | +|------------------|---------|---------------| +| Field label | Identifies the field permanently | Always visible, above or beside the field | +| Placeholder text | Shows format or example | Disappears on focus; never replace a label with a placeholder | +| Helper text | Provides constraints or guidance | Below the field, always visible | +| Character counter | Shows remaining capacity | "23 / 280" for length-limited fields | +| Required indicator | Marks mandatory fields | Asterisk (*) or "(required)" text | + +### Icons as Signifiers + +| Icon | Universal Meaning | Potential Ambiguity | +|------|------------------|-------------------| +| Magnifying glass | Search | Could mean "zoom" in image contexts | +| Gear / cog | Settings | Could mean "processing" or "tools" | +| Pencil | Edit | Could mean "compose" or "draw" | +| Trash can | Delete | Clear vs. delete distinction may be unclear | +| Heart | Like / favorite | Could mean "health" in medical apps | +| Bell | Notifications | Could mean "alerts" or "alarms" | +| Share (arrow from box) | Share content | Platform-specific: different icons on iOS vs. Android | + +**Rule**: When an icon's meaning is even slightly ambiguous, pair it with a text label. + +### Color as Signifier + +| Color | Common Signification | Caution | +|-------|---------------------|---------| +| Blue | Clickable / interactive / link | Must not be used for non-interactive text | +| Red | Error / danger / destructive action | Cultural variation: red means luck in China | +| Green | Success / safe / positive action | Do not rely on color alone (color blindness) | +| Yellow / amber | Warning / caution | Low contrast on white backgrounds | +| Gray | Disabled / inactive / secondary | Can also mean "subtle" rather than "disabled" | + +### Position as Signifier + +| Position | What It Signals | Convention | +|----------|----------------|------------| +| Top-left | Logo / home link | Almost universal on web | +| Top-right | User account, settings, cart | Strong web convention | +| Bottom of screen (mobile) | Primary navigation | iOS tab bar, Android bottom nav | +| Top-right of a card or modal | Close button | X icon in corner | +| Bottom-right of a form | Primary action button | "Submit", "Save", "Next" | +| Inline, right of content | Edit or action for that content | Pencil icon next to a heading | + +--- + +## Signifier Hierarchy: When Multiple Signifiers Compete + +When a screen contains many signifiers, they compete for attention. A hierarchy prevents visual overload and guides users to the most important actions first. + +### Establishing Hierarchy + +| Level | Treatment | Use For | +|-------|-----------|---------| +| **Primary** | Large, high-contrast, filled color, prominent position | The single most important action (e.g., "Buy Now") | +| **Secondary** | Medium size, outlined or muted color | Supporting actions (e.g., "Add to Wishlist") | +| **Tertiary** | Small, text-only or icon-only, low contrast | Minor actions (e.g., "Share", "Report") | +| **Ambient** | Subtle, always-present, low visual weight | Navigation, status indicators, breadcrumbs | + +### Common Hierarchy Mistakes + +- **Multiple primary buttons on one screen**: Users cannot tell which action matters most. Limit to one primary button per view. +- **Competing colors**: Using red, blue, green, and orange buttons on the same screen creates visual noise. Use one accent color for primary actions. +- **Equal-weight labels**: When every label is the same size and weight, nothing stands out and users scan randomly. + +--- + +## Cultural Signifiers and Localization + +Signifiers carry cultural meaning that does not always translate across regions. + +| Signifier | Western Interpretation | Alternate Interpretation | +|-----------|----------------------|------------------------| +| Red color | Danger, error, stop | Luck, prosperity (East Asia) | +| Green color | Success, go, safe | Islam, nature (Middle East) | +| Thumbs up icon | Approval, "like" | Offensive in some Middle Eastern cultures | +| Checkmark | Correct, done | Can mean "incorrect" in Japan and Korea | +| Owl icon | Wisdom, knowledge | Bad luck, death omen (some Asian cultures) | +| Left-to-right arrow | Forward, next | Means "back" in RTL languages (Arabic, Hebrew) | + +### Localization Checklist + +- [ ] Review all icons for cultural sensitivity in target markets. +- [ ] Ensure directional signifiers (arrows, progress bars) adapt to RTL layouts. +- [ ] Do not rely solely on color to convey meaning. +- [ ] Test signifier comprehension with users from target cultures. +- [ ] Provide text labels alongside icons in localized versions. + +--- + +## Over-Signifying vs. Under-Signifying + +### Under-Signifying + +Too few cues. Users cannot find features or realize elements are interactive. Symptoms: "What do I do here?", low discovery rates, support tickets for features that exist, clicks on non-interactive elements. + +### Over-Signifying + +Too many cues. Visual noise overwhelms users and nothing stands out. Symptoms: users feel overwhelmed, task completion time increases, interface described as "cluttered", primary actions missed. + +### Finding the Balance + +| Principle | Implementation | +|-----------|---------------| +| Signal-to-noise ratio | Every signifier should earn its place. Remove any that do not directly help users complete a task. | +| Progressive disclosure | Show essential signifiers first; reveal advanced ones on demand. | +| Consistent patterns | When users learn one signifier pattern, they apply it everywhere. Fewer unique patterns needed. | +| Whitespace as signifier | Empty space around an element signals importance. Let key elements breathe. | + +--- + +## Signifier Design Patterns by Component Type + +### Navigation + +- Use text labels, not just icons, for primary navigation items. +- Highlight the current page or section with color, underline, or bold weight. +- Show the user's position in the hierarchy (breadcrumbs, highlighted nav item). +- Use a chevron or arrow to indicate dropdowns and expandable sections. + +### Forms + +- Label every field (above or to the left). +- Mark required fields with an asterisk and explain the convention. +- Show validation state inline (green check, red X) as the user fills in fields. +- Use helper text below fields for format requirements ("MM/DD/YYYY"). +- Group related fields with visible section headers. + +### Data Tables + +- Make sortable columns obvious with a sort icon (arrows up/down). +- Show which column is currently sorted with a filled or highlighted icon. +- Use row hover states to signal that rows are interactive. +- Provide column header tooltips for abbreviated labels. + +### Modals and Dialogs + +- Always include a visible close button (X in top-right corner). +- Dim the background to signify the modal is the active layer. +- Label action buttons clearly ("Delete Account" not just "OK"). +- Use a destructive color (red) for irreversible action buttons. + +--- + +## Testing Signifier Effectiveness + +### Five-Second Test + +Show the interface to a user for exactly 5 seconds, then hide it. Ask: +1. What was this page about? +2. What could you do on this page? +3. What would you click first? + +If users cannot answer these questions, signifiers are insufficient. + +### First-Click Test + +Give users a task and record where they click first. If fewer than 70% of users click the correct target on the first attempt, the signifier for that target is too weak. + +### Think-Aloud Walkthrough + +Ask users to complete a task while narrating their thought process. Listen for: +- "I'm not sure what to click." +- "Is this a button?" +- "What does this icon mean?" +- "I didn't notice that." + +Each statement identifies a signifier failure. + +--- + +## Signifier Audit Checklist + +### Visibility + +- [ ] Every interactive element has at least one visible signifier. +- [ ] Primary actions have the strongest visual signifiers (size, color, position). +- [ ] Secondary actions are visually subordinate to primary actions. +- [ ] System state is visible at all times (logged in, unsaved changes, current mode). + +### Clarity + +- [ ] Icons are paired with text labels (or tooltips at minimum). +- [ ] Color is not the sole signifier for any piece of information. +- [ ] Cursor changes are implemented for all interactive elements (desktop). +- [ ] Placeholder text does not replace labels. + +### Consistency + +- [ ] The same signifier pattern means the same thing everywhere in the product. +- [ ] Interactive elements are visually consistent (all buttons look like buttons). +- [ ] Position conventions are maintained (close in top-right, primary action in bottom-right). +- [ ] Color meanings are consistent (red always means error/danger, green always means success). + +### Accessibility + +- [ ] Signifiers work without color (underline, border, icon, or shape also used). +- [ ] Focus indicators are visible for keyboard navigation. +- [ ] Screen reader users receive equivalent signifier information via ARIA labels and roles. +- [ ] Animation-based signifiers have non-animated alternatives. + +--- + +## Before/After Examples + +### Example 1: Unlabeled Icon Toolbar + +**Before**: A toolbar with 8 monochrome icons and no text. New users hover over each icon one by one to discover tooltips. Many icons are ambiguous (what does the diamond icon do?). + +**After**: Each icon has a small text label beneath it. The most-used 5 icons are always visible; 3 less-used icons are grouped under a "More" menu. Users find features 3x faster. + +### Example 2: Invisible Toggle + +**Before**: A settings page lists options with a small circular dot next to each. The dot is the toggle, but it looks like a bullet point. Users do not know the settings are changeable. + +**After**: Each option has a standard toggle switch (track with a sliding circle) using green/gray color states. Users immediately understand they can turn options on and off. + +### Example 3: Mystery Status Indicator + +**Before**: A colored circle in the header changes from green to yellow to red. No legend or tooltip explains what the colors mean. Users speculate about its meaning. + +**After**: The circle is replaced with a text badge: "All Systems Operational" (green), "Degraded Performance" (yellow), "Outage Detected" (red). The meaning is immediately clear. diff --git a/.agents/skills/design-everyday-things/references/two-gulfs.md b/.agents/skills/design-everyday-things/references/two-gulfs.md new file mode 100644 index 00000000..6e7c1811 --- /dev/null +++ b/.agents/skills/design-everyday-things/references/two-gulfs.md @@ -0,0 +1,235 @@ +# The Two Gulfs: Execution and Evaluation + +Every human-product interaction involves crossing two psychological chasms. The Gulf of Execution separates what the user wants to do from the actions the product requires. The Gulf of Evaluation separates what the product did from the user's understanding of what happened. Narrowing these gulfs is the central challenge of interaction design. + +## Gulf of Execution: The Gap Between Intent and Action + +The Gulf of Execution exists whenever a user has a goal but cannot figure out how to achieve it. The wider the gulf, the more effort users must expend translating their intentions into physical actions. + +### What Makes the Gulf Wide + +| Factor | Description | Example | +|--------|-------------|---------| +| Hidden controls | Actions exist but users cannot find them | Swipe gestures with no visual indicator | +| Unfamiliar vocabulary | Labels use jargon or internal terminology | "Reconcile ledger" instead of "Match payments" | +| Non-obvious sequences | Multiple steps required with no guidance | Configuring a router through 7 unlabeled screens | +| Mismatched mappings | Controls don't correspond to outcomes | A row of identical switches controlling different zones | +| Missing affordances | Interactive elements look static | A clickable text block with no hover state, underline, or color | + +### What Narrows the Gulf + +| Strategy | How It Works | Example | +|----------|-------------|---------| +| Clear signifiers | Visual cues reveal available actions | Placeholder text reading "Search by name or email..." | +| Natural mappings | Controls spatially match outputs | Volume slider oriented vertically, up means louder | +| Constraints | Only valid actions are possible | Date picker prevents invalid date entry | +| Familiar patterns | Use conventions users already know | Shopping cart icon in the top-right corner | +| Progressive disclosure | Show relevant options at the right time | Payment fields appear only after "Checkout" is clicked | + +### Gulf of Execution in Web Applications + +Web apps frequently widen the Gulf of Execution by burying functionality. Common offenders: + +- **Hamburger menus on desktop**: Users cannot see what actions are available without clicking an icon that many people do not recognize. +- **Icon-only toolbars**: Without labels, users must guess what each icon does. A floppy disk icon means "save" only to users who have seen floppy disks. +- **Right-click dependent actions**: Any action that requires right-clicking is invisible to most users. +- **Keyboard-shortcut-only features**: Power users love them, but they are undiscoverable without signifiers. + +### Gulf of Execution in Mobile Apps + +- **Gesture-only navigation**: Swipe-to-delete, pull-to-refresh, and pinch-to-zoom all have wide execution gulfs for new users. +- **Hidden bottom sheets**: Content tucked behind a drag handle that looks decorative. +- **Long-press menus**: No visual indicator that holding down on an element reveals additional options. + +### Gulf of Execution in Physical Products + +- **Flat push-plates on doors that need to be pulled**: The plate affords pushing, but the door requires pulling. +- **Stove knobs in a row**: Four knobs in a line controlling burners in a 2x2 grid. Users cannot tell which knob maps to which burner. +- **Shower controls with unmarked handles**: Hot, cold, and diverter valves with no labels or color coding. + +--- + +## Gulf of Evaluation: The Gap Between System State and Understanding + +The Gulf of Evaluation exists whenever a user has performed an action but cannot determine what happened, whether it worked, or what state the system is now in. + +### What Makes the Gulf Wide + +| Factor | Description | Example | +|--------|-------------|---------| +| No feedback | Action produces no visible response | Clicking a button with no loading indicator or confirmation | +| Delayed feedback | Response comes seconds or minutes later | Email sent with no confirmation; user wonders if it went | +| Ambiguous feedback | Something changed but meaning is unclear | A number changed from 3 to 4 with no explanation | +| Hidden state | System state is not visible | Background sync happening with no indicator | +| Technical error messages | Error text is not human-readable | "Error 0x80070005: Access denied" | + +### What Narrows the Gulf + +| Strategy | How It Works | Example | +|----------|-------------|---------| +| Immediate feedback | Visual response within 100ms | Button depresses and changes color on click | +| State indicators | Persistent display of current state | "Draft" / "Published" badge on documents | +| Progress communication | Show advancement toward goal | "Step 3 of 5" with a progress bar | +| Clear error messages | Explain what happened and how to fix it | "That email is already registered. Try logging in instead." | +| Meaningful transitions | Animations that explain change | A deleted item sliding off-screen to the trash | + +### Gulf of Evaluation in Web Applications + +- **Silent saves**: Auto-save is excellent, but without a "Saved" indicator, users repeatedly click save. +- **Pagination with no count**: Users cannot tell how much content exists or where they are in the set. +- **Background processing**: File uploads, exports, or calculations with no progress indicator. +- **Form submission without redirect or toast**: Users click "Submit" and nothing visibly changes. + +### Gulf of Evaluation in Kiosks and Public Terminals + +- **Airport check-in kiosks**: Users scan their passport but receive no confirmation for 3-5 seconds. Many scan again, causing errors. +- **Parking meters**: Payment accepted but the display returns to the default screen before the user reads the confirmation. +- **Self-checkout machines**: Weight sensor errors display cryptic messages, and the machine locks until an attendant arrives. + +--- + +## Gulf Analysis Exercise Template + +Use this template to analyze any interface by examining both gulfs for a specific user task. + +### Step 1: Define the Task + +| Field | Entry | +|-------|-------| +| **Product / Interface** | | +| **User goal** | | +| **Target user profile** | | +| **Context of use** | | + +### Step 2: Analyze the Gulf of Execution + +| Question | Assessment (1-5) | Notes | +|----------|:-----------------:|-------| +| Can the user identify what actions are available? | | | +| Are the correct controls visible and discoverable? | | | +| Do the controls use familiar patterns and vocabulary? | | | +| Is the mapping between controls and outcomes clear? | | | +| Are impossible or irrelevant actions constrained? | | | +| Is the required sequence of steps obvious? | | | +| **Execution Gulf Score (average)** | | | + +### Step 3: Analyze the Gulf of Evaluation + +| Question | Assessment (1-5) | Notes | +|----------|:-----------------:|-------| +| Does the system provide immediate feedback on actions? | | | +| Can the user determine the current system state? | | | +| Is the feedback informative and understandable? | | | +| Are error states clearly communicated with recovery steps? | | | +| Can the user confirm the goal was achieved? | | | +| Are transitions and state changes visible? | | | +| **Evaluation Gulf Score (average)** | | | + +### Step 4: Identify Improvements + +| Gulf | Problem Found | Severity (H/M/L) | Proposed Fix | +|------|--------------|:-----------------:|-------------| +| Execution | | | | +| Execution | | | | +| Evaluation | | | | +| Evaluation | | | | + +--- + +## Measuring Gulf Width: A Heuristic Evaluation Approach + +Gulf width is not a single number. It varies by user expertise, context, and task. Use these heuristics to estimate relative width. + +### Execution Gulf Width Indicators + +| Width | Characteristics | +|-------|----------------| +| **Narrow** | User completes the action on first attempt without hesitation. Controls are visible, labeled, and follow conventions. | +| **Medium** | User pauses, scans the interface, then finds the correct action. Minor exploration required. | +| **Wide** | User tries incorrect actions before finding the right one, or gives up and seeks help. | +| **Very wide** | User cannot complete the task without external instruction (manual, tutorial, another person). | + +### Evaluation Gulf Width Indicators + +| Width | Characteristics | +|-------|----------------| +| **Narrow** | User immediately understands what happened and confirms the result. No uncertainty. | +| **Medium** | User notices a change but takes a moment to interpret it. Brief confusion, then clarity. | +| **Wide** | User is unsure whether the action succeeded. May repeat the action or navigate away to verify. | +| **Very wide** | User has no idea what the system did. Cannot determine current state. Abandons or calls support. | + +--- + +## Design Patterns That Widen Each Gulf + +### Patterns That Widen the Execution Gulf + +- **Mystery meat navigation**: Links or icons with no labels that reveal their purpose only on hover or click. +- **Modes without indicators**: The interface behaves differently depending on an invisible mode (edit mode vs. view mode with no visual distinction). +- **Nested menus beyond two levels**: Users must remember a path through multiple levels to reach a function. +- **Inconsistent action locations**: "Save" is in the toolbar on one screen, in the footer on another, and in a menu on a third. +- **Custom scrollbars that hide**: Disappearing scrollbars on content that is not obviously scrollable. + +### Patterns That Widen the Evaluation Gulf + +- **Toasts that disappear too quickly**: Success or error messages that vanish in under 2 seconds before users read them. +- **Silent failures**: An action fails but the interface shows no error, giving the impression of success. +- **Optimistic UI without correction**: The interface shows success immediately but never corrects if the server rejects the action. +- **Identical states**: A toggle switch where "on" and "off" look nearly the same. +- **Aggregate indicators**: A single status badge that combines multiple states (e.g., "3 issues" with no breakdown). + +--- + +## Patterns That Narrow Each Gulf + +### Patterns That Narrow the Execution Gulf + +- **Visible toolbars with text labels**: Every action is one click away with a clear label. +- **Contextual actions**: Relevant actions appear near the content they affect (inline edit buttons, contextual menus on selection). +- **Command palettes**: A searchable list of all available actions, bridging the gap for users who know what they want but not where it is. +- **Onboarding spotlights**: First-time highlights that point out key controls. +- **Consistent layout grids**: Users learn where to look for actions because they are always in the same place. + +### Patterns That Narrow the Evaluation Gulf + +- **Persistent status bars**: Always-visible indicators of system state (connection status, save status, user role). +- **Inline validation**: Real-time feedback on form fields as the user types. +- **Undo toasts with timers**: "Message sent. Undo (5s)" gives confirmation and a recovery window simultaneously. +- **State-change animations**: Smooth transitions that show how the old state became the new state. +- **Confirmation screens**: A summary of what was just done with the option to modify. + +--- + +## Worksheet: Analyze Any Interface Through the Two Gulfs + +Use this quick-reference worksheet for a 15-minute audit of any product or feature. + +### Instructions + +1. Choose a specific task the user wants to accomplish. +2. Attempt the task yourself as if you were a new user. +3. At each moment of hesitation, note which gulf is too wide. +4. Fill in the table below. + +| Step | What I Wanted to Do | What I Actually Did | Gulf Issue (Execution / Evaluation) | Severity | Fix | +|:----:|---------------------|--------------------|------------------------------------|:--------:|-----| +| 1 | | | | | | +| 2 | | | | | | +| 3 | | | | | | +| 4 | | | | | | +| 5 | | | | | | + +### Summary + +- **Total execution issues found**: ___ +- **Total evaluation issues found**: ___ +- **Widest gulf moment**: ___ +- **Highest-priority fix**: ___ +- **Overall gulf assessment**: The [execution / evaluation] gulf is the bigger problem for this task. + +### Follow-Up Actions + +- [ ] Prioritize fixes by severity +- [ ] Sketch improved designs for the widest gulf moments +- [ ] Test improved designs with 3-5 users +- [ ] Re-evaluate gulf width after changes diff --git a/.agents/skills/design-sprint/SKILL.md b/.agents/skills/design-sprint/SKILL.md new file mode 100644 index 00000000..e8f4d92f --- /dev/null +++ b/.agents/skills/design-sprint/SKILL.md @@ -0,0 +1,239 @@ +--- +name: design-sprint +description: 'Run a structured 5-day process to prototype, test, and validate product ideas with real users. Use when the user mentions "design sprint", "validate before we build", "rapid prototype", "test with users", or "should we build this". Also trigger when a team is stuck in endless debate over a high-stakes product decision, or wants to de-risk a costly idea before investing in development. Covers mapping, sketching, deciding, prototyping, and testing across Monday-Friday. For ongoing experimentation and MVPs, see lean-startup. For customer job analysis, see jobs-to-be-done. For non-leading user interviews, see mom-test.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Design Sprint Framework + +A five-day process for answering critical business questions through design, prototyping, and testing ideas with customers. Developed at Google Ventures and used by Google, Slack, Airbnb, and hundreds of startups. + +## Core Principle + +**Compress months of debate, design, and testing into one week — and test with real users before writing any production code.** The sprint replaces endless discussion with a fixed Monday-to-Friday spine, hard time-boxes, and a single Decider, so a high-stakes product question gets a real answer in five days instead of five months. + +## Scoring + +**Goal: 10/10.** Score a sprint plan or execution by awarding 1 point for each item present and correct (10 total). Report the score and the missing items needed to reach 10/10. + +1. Decider committed for the full week; one Sprint Master facilitating. +2. Monday produces a target customer and moment (not a vague "test the product"). +3. Hard time-boxes used (Crazy 8s in 8 min, 10am-5pm days, no open-ended sessions). +4. Solution sketches done alone and anonymous — no group brainstorming. +5. Wednesday ends with a single Decider Supervote, not consensus. +6. Storyboard specified before any prototype is built. +7. Prototype is a Goldilocks-fidelity facade, testable in 5-15 min, with a trial run done. +8. Exactly 5 target users recruited via screener (6 scheduled to absorb a no-show). +9. Friday uses the Five-Act Interview; users interpret the prototype unexplained. +10. End-of-sprint debrief converts the +/-/~ pattern grid into a decision on next steps. + +A plan missing the Decider, real users, or a same-day prototype caps at 6 — those are the failure modes the sprint exists to prevent. + +## The 5-Day Sprint Process + +``` +Monday → Tuesday → Wednesday → Thursday → Friday + Map Sketch Decide Prototype Test +``` + +**Prerequisites:** a big challenge worth a week's focus; the right team (Decider plus 4-7 people with diverse expertise); five full days (10am-5pm) with no interruptions; a dedicated room with whiteboards. One **Sprint Master** facilitates, keeps time, and manages energy. + +See [references/facilitation.md](references/facilitation.md) when you are the Sprint Master — it has the full facilitation guide, time-boxing tactics, and energy-management moves for keeping a stuck or low-energy room productive. + +## Monday: Map + +**Goal:** Understand the problem and choose a target for the week. + +### Morning: Start at the End + +- **Long-term goal:** Write the optimistic answer to "What do we want to be true in 2 years?" — e.g., "Customers use our product daily." +- **Sprint questions:** List obstacles and unknowns as questions on the whiteboard, whole team contributing — e.g., "Will customers trust us with payment info?" + +### Afternoon: Map the Challenge + +- **Customer journey map:** List the actors (customer types), then draw the journey left to right in 5-15 steps: "Hears about product → Visits site → Signs up → First use → Regular user." +- **Ask the Experts:** Interview teammates with specialized knowledge (CEO, design, engineering, support, sales); capture notes on the whiteboard. +- **How Might We (HMW):** Rephrase problems as opportunities — "Customers don't understand pricing" → "HMW make pricing immediately clear?" One per sticky note; vote and organize the best on the map. + +### End of Day: Pick a Target + +Choose which customer and moment on the map to focus on — the biggest risk or opportunity (e.g., "the first 10 minutes after signup"). The **Decider** (person with authority) makes the final call. + +**Monday output:** long-term goal, sprint questions, journey map, expert insights, organized HMW notes, target customer and moment. + +See [references/monday.md](references/monday.md) while facilitating Monday — step-by-step exercise scripts, HMW examples, and the target-selection method. + +## Tuesday: Sketch + +**Goal:** Generate solutions — each person sketches a detailed solution. + +### Morning: Lightning Demos + +- **Find inspiration:** 3-minute demos of competitors and analogous products ("Here's what I found, here's why it's interesting"); capture good ideas on the whiteboard. Borrow from any industry. +- **Divide or swarm:** Split the map between people if it has multiple parts; otherwise everyone tackles the same critical problem (most sprints swarm). + +### Afternoon: The Four-Step Sketch + +Everyone sketches alone — **no group brainstorming**. Individual work produces better, more diverse ideas. + +1. **Notes (20 min):** Silently walk the room reviewing the map, HMWs, and inspiration. +2. **Ideas (20 min):** Rough doodles, mind maps, stick figures — quantity over quality. +3. **Crazy 8s (8 min):** Fold paper into 8 panels and sketch 8 variations in 8 minutes — forces you past your first idea. +4. **Solution Sketch (30-90 min):** A 3-panel storyboard of the customer experience (beginning, middle, end). Make it self-explanatory, give it a catchy title, and keep it **anonymous**. + +**Tuesday output:** one detailed, anonymous, self-explanatory solution sketch per person. + +See [references/tuesday.md](references/tuesday.md) before the Four-Step Sketch — Crazy 8s and solution-sketch templates plus worked examples to show the team. + +## Wednesday: Decide + +**Goal:** Critique solutions and choose the best one to prototype and test. + +### Morning: Sticky Decision + +- **Art museum:** Tape sketches to the wall; review silently (no talking) and mark interesting parts with dot stickers. +- **Heat map review:** Discuss each sketch for 3 minutes — the facilitator narrates while the anonymous sketcher stays silent; a scribe captures standout ideas on the whiteboard. +- **Straw poll:** Each person votes for one solution with one sentence of rationale (non-binding). +- **Supervote:** The Decider gets three large dots; their decision wins. + +### Afternoon: Rumble or All-in-One + +If multiple sketches win, choose: **Rumble** (competing prototypes testing different approaches) or **All-in-One** (combine the best ideas into one prototype — simpler, and what most sprints do). + +- **Storyboard:** Draw a 10-15 panel comic of the test experience: opening scene (how the customer discovers you) → your solution in action → successful outcome. Keep it simple — stick figures, words, arrows — but get specific about the UI. Include just enough detail for Thursday's prototype. + +**Wednesday output:** winning solution(s) and a detailed storyboard ready to prototype. + +See [references/wednesday.md](references/wednesday.md) when running the Sticky Decision and storyboard — facilitation steps for the vote and a panel-by-panel storyboard template. + +## Thursday: Prototype + +**Goal:** Build a realistic facade in one day — you need something to test on Friday. + +**Mindset:** Fake it; prototype only what you'll test. Aim for Goldilocks fidelity — sketches are too low for honest reactions, working code wastes time. It should look real without working for real (facades, click-throughs, video). + +### Assign Roles + +| Role | Responsibility | +|------|----------------| +| **Makers** (2+) | Build the prototype pieces (design, assets) | +| **Stitcher** (1) | Combines pieces into the final prototype (Keynote, Figma) | +| **Writer** (1) | All copy: headlines, button labels, descriptions | +| **Collector** (1-2) | Gathers photos, icons, competitor screenshots | +| **Interviewer** (1) | Writes and rehearses Friday's interview script | +| **Sprint Master** | Helps where needed, keeps energy up | + +### Build the Prototype + +**Tools:** Figma, Keynote, or PowerPoint linked slides for web/apps; video walkthrough or 3D-printed mockup for physical products; role-play video or scripted interaction for services. + +Morning: divide the storyboard into scenes and assign them to makers. Afternoon: stitch together, review against the storyboard, rehearse the full flow, and run a trial with someone outside the sprint team. + +**Prototype checklist:** +- [ ] Follows storyboard exactly +- [ ] Looks real enough to get honest reactions +- [ ] Can walk through in 5-15 minutes +- [ ] Interviewer knows how to present it +- [ ] Trial run completed + +**Thursday output:** realistic prototype, interview script, prepared interview room. + +See [references/thursday.md](references/thursday.md) while building the prototype — tool-by-tool techniques (Keynote/Figma facades, video, mockups) for hitting Goldilocks fidelity in a day. + +## Friday: Test + +**Goal:** Interview 5 customers; learn what works and what doesn't. + +### Setup + +Interview room: quiet space, laptop with the prototype, camera recording screen and customer's face. Observation room: live video feed where the whole team watches and takes notes on a whiteboard. One **Interviewer** conducts all five interviews. + +### The Five-Act Interview + +About 45 minutes per customer (the five acts run ~35 min plus setup and transitions), with 30-minute breaks between to discuss observations and adjust questions. See references/friday.md for the full 9am-5pm schedule. + +| Act | Time | What to Do | +|-----|------|------------| +| **1. Friendly welcome** | 5 min | Greet warmly; explain you're testing the prototype, not them; get recording permission; encourage thinking aloud | +| **2. Context questions** | 5 min | "Tell me about how you currently handle [problem]" — understand mindset and current behavior | +| **3. Introduce prototype** | 5 min | "What's this? What do you think it's for?" Don't explain — let them interpret | +| **4. Tasks and nudges** | 15 min | Open-ended exploration, then storyboard tasks. When stuck: "What would you do next?", "What's going through your mind?" Don't help — watch them struggle | +| **5. Debrief** | 5 min | "What did you think overall?", "Who is this for?", "What worked? What was confusing?" | + +### Five Is the Magic Number + +Patterns emerge after 3-5 people and returns diminish after 5 — and five interview-plus-break slots fit one day (see references/friday.md). Recruit target customers via a screener survey and offer an incentive ($100-$200 B2B, $50-$100 B2C). + +See [references/recruiting.md](references/recruiting.md) two weeks before the sprint — it has screener-survey questions, recruiting channels, scheduling logistics, and incentive guidance for locking in five on-target users. + +### Take Notes: Pattern Recognition + +Capture observations in a grid, one column per customer: + +| Customer 1 | Customer 2 | Customer 3 | Customer 4 | Customer 5 | +|------------|------------|------------|------------|------------| +| notes | notes | notes | notes | notes | + +Mark each observation **✓** (positive, success), **✗** (negative, failure), or **~** (neutral/mixed). After all five interviews, count marks per row and look for patterns — did all 5 struggle with the same thing? + +### End-of-Sprint Debrief + +Organize findings: **✓ what worked** (flows everyone understood, messaging that resonated), **✗ what failed** (confusing terminology, missing steps, wrong assumptions), **~ mixed** (some got it, some didn't). Then decide next steps: + +- **Core concept validated:** build it, or run the next sprint on details +- **Major issues:** pivot, or sprint again on the problems +- **Total failure:** back to the drawing board — you just saved months + +**Friday output:** interview recordings, pattern notes, a clear list of what works and what doesn't, decision on next steps. + +See [references/friday.md](references/friday.md) before interviewing — verbatim Five-Act scripts, note-taking templates, the fuller next-steps decision table, and the common Friday mistakes to avoid. + +## When to Run a Design Sprint + +**Run when:** the decision is high-stakes, there's no time to build and test normally, the team is stuck in endless debate, multiple solutions compete, it's a new product/feature/major redesign, or you need to de-risk before investing. + +**Don't run when:** the problem and solution are obvious and you just need to execute, the team isn't bought in, or you can't get the Decider for the full week. + +See [references/case-studies.md](references/case-studies.md) for worked sprint walk-throughs (Slack, Blue Bottle Coffee, Savioke and more) when you need a concrete precedent for how a sprint played out in a domain like yours. + +## Variations + +- **4-Day Sprint:** Day 1 Map + Sketch (compressed), Day 2 Decide, Day 3 Prototype, Day 4 Test. +- **Remote Sprint:** Same schedule with Miro/FigJam whiteboards and Zoom. See [references/remote-sprints.md](references/remote-sprints.md) when the team is distributed — it adapts each exercise to digital whiteboards, sets remote time-boxes, and handles video-based prototype testing. +- **Multi-Sprint:** Sprint 1 chooses direction on a broad problem, Sprint 2 deep-dives the chosen solution, Sprint 3 refines details. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|------| +| **Skip prototyping** | Nothing to test | Always prototype, even if simple | +| **Over-engineer prototype** | Waste time on details that don't matter | Facade only, not working code | +| **Test with wrong users** | Invalid feedback | Screen for target customers | +| **Explain prototype to users** | Defeats the test; confusion is the data | Run Acts 3-4 as written — they interpret and struggle unaided | +| **No decision maker** | Can't commit to decision | Get Decider for full week or don't sprint | +| **Interruptions** | Breaks focus | Protect the week, no meetings/emails | + +## Quick Diagnostic + +Audit any sprint plan: + +| Question | If No | Action | +|----------|-------|--------| +| Do we have a Decider for full week? | Sprint will fail | Get commitment or postpone | +| Is the problem important enough? | Waste of time | Only sprint on big challenges | +| Can we prototype in 1 day? | Wrong problem for sprint | Choose more concrete problem | +| Can we recruit 5 target users? | Can't test properly | Start recruiting now (2 weeks ahead) | +| Will team commit to no interruptions? | Won't maintain focus | Get buy-in from leadership | + +## Further Reading + +For the complete methodology, exercises, and case studies: + +- [*"Sprint: How to Solve Big Problems and Test New Ideas in Just Five Days"*](https://www.amazon.com/Sprint-Solve-Problems-Test-Ideas/dp/150112174X?tag=wondelai00-20) by Jake Knapp, John Zeratsky, Braden Kowitz + +## About the Author + +**Jake Knapp** created the Design Sprint at Google, where he ran sprints on Gmail, Chrome, and Google X, then refined the process across 100+ startup sprints as a design partner at Google Ventures. The sprint is now used at Google, Slack, Airbnb, LEGO, and thousands of companies worldwide. He is also the author of *Make Time*. diff --git a/.agents/skills/design-sprint/references/case-studies.md b/.agents/skills/design-sprint/references/case-studies.md new file mode 100644 index 00000000..210b6b7b --- /dev/null +++ b/.agents/skills/design-sprint/references/case-studies.md @@ -0,0 +1,257 @@ +# Design Sprint Case Studies + +These case studies illustrate how real teams used the design sprint process to solve critical business problems. Each study follows the five-day structure and highlights what worked, what did not, and what lessons emerged. The companies range from well-funded startups to large enterprises to nonprofits. + +## Case Study 1: Slack - Onboarding New Teams + +### Company + +Slack, the workplace messaging platform. At the time of this sprint, Slack was growing rapidly but facing a critical problem: many teams signed up but never became active users. + +### Challenge + +New teams would create a Slack workspace, invite a few colleagues, and then go quiet within 48 hours. The data showed that teams who sent 2,000 messages within the first week had a 93% retention rate, but most teams never reached that threshold. The sprint question: "How might we get new teams to their first 2,000 messages faster?" + +### Sprint Process + +**Monday:** The team mapped the journey from "admin creates workspace" to "team sends 2,000 messages." They identified a critical gap: after the admin invited colleagues, those colleagues received a generic email that did not explain why they should join or what to do first. The target became the first 30 minutes after a team member accepts the invitation. + +**Tuesday:** Lightning Demos included how Duolingo gets users to complete their first lesson within 60 seconds and how multiplayer games create immediate social interactions. The team sketched solutions ranging from a guided onboarding wizard to a bot that would prompt conversation topics. + +**Wednesday:** The winning sketch was "Slackbot Welcome," a concept where an AI bot would greet each new team member, ask them a fun question, and post their answer in the general channel, creating immediate social activity. + +**Thursday:** The team prototyped a click-through showing the invitation email (redesigned with a clear value proposition), the first login experience, and the Slackbot interaction. They used Figma for the app screens and rewrote the email copy to emphasize team connection rather than product features. + +**Friday:** 5 participants (team leads at small companies) walked through the prototype. 4 out of 5 said they would respond to the Slackbot question. 3 out of 5 said the redesigned email made them significantly more likely to click through compared to the existing email. + +### Results + +The redesigned invitation email increased click-through rates by 30% in subsequent A/B testing. The Slackbot conversation starter was refined over several iterations and became part of the default onboarding flow. + +### Lessons + +- The biggest opportunity was not in the product interface but in the email that brought people to the product +- Social interaction (not feature discovery) was the key driver of early retention +- The team's initial assumption that users needed a "product tour" was wrong; users needed a reason to talk + +## Case Study 2: Blue Bottle Coffee - Online Store + +### Company + +Blue Bottle Coffee, a specialty coffee roaster known for its carefully curated in-store experience. They wanted to translate that experience to e-commerce. + +### Challenge + +Blue Bottle's existing online store looked and felt like every other e-commerce site: grid of products, add to cart, checkout. It did not communicate their brand's emphasis on freshness, origin, and craft. The sprint question: "Can we create an online buying experience that feels as personal as visiting a Blue Bottle cafe?" + +### Sprint Process + +**Monday:** The team mapped the in-store experience alongside the online experience. In-store, a barista asks what flavors you like and recommends a coffee. Online, customers stared at 40 bags of coffee with no guidance. The target: the moment a new customer decides which coffee to buy. + +**Tuesday:** Lightning Demos included how Stitch Fix uses a style quiz to personalize recommendations, how wine apps describe flavor profiles visually, and how the Blue Bottle barista script actually works in stores. Solution sketches ranged from a "coffee quiz" to a curated subscription to a visual flavor map. + +**Wednesday:** The Decider chose a combination: a simple 3-question quiz ("What do you usually drink? How do you brew? What flavors do you like?") followed by a personalized recommendation with tasting notes and origin story. + +**Thursday:** The prototype was built in Keynote with linked slides. Each quiz answer led to a different recommendation page. The team wrote detailed copy for 4 different coffee recommendations, including origin stories, roast dates, and brewing tips. + +**Friday:** 5 participants (regular online coffee buyers who had never tried Blue Bottle) tested the prototype. All 5 completed the quiz. 4 out of 5 said the recommendation felt personal and trustworthy. 3 out of 5 said they would pay a premium because the quiz made them feel confident in the choice. 1 participant said "This is like having a barista in my phone." + +### Results + +Blue Bottle launched a version of the coffee quiz on their website. It became one of the highest-converting entry points for new customers and was later adapted for their mobile app. + +### Lessons + +- Translating a physical experience to digital requires identifying the core emotional value, not just the functional steps +- A quiz format transforms a passive catalog into an interactive experience +- Customers will pay more when they feel guided rather than overwhelmed by choice + +## Case Study 3: Savioke - Robot Hotel Delivery + +### Company + +Savioke, a robotics startup building autonomous delivery robots for hotels. Their robot, Relay, delivered items like toothbrushes and snacks from the front desk to guest rooms. + +### Challenge + +The robot worked technically, but hotels were hesitant to adopt it. The sprint question: "Will hotel guests react positively to a robot delivering items to their room, and will hotels see it as a brand enhancer rather than a gimmick?" + +### Sprint Process + +**Monday:** The team mapped the guest experience from calling the front desk to receiving the item. They identified two critical moments: the guest's first sight of the robot in the hallway and the handoff at the guest room door. The target: the doorway interaction when the robot arrives. + +**Tuesday:** Lightning Demos included how Disney designs character interactions at theme parks (anticipation, surprise, delight), how Amazon delivery confirms successful drop-off, and how vending machines provide instant gratification. Sketches explored different robot behaviors: should it make sounds? Display a screen? Wait for the guest to open the door? + +**Wednesday:** The winning concept featured a robot that calls the guest's room phone to announce arrival, displays a friendly message on its screen, opens its lid for the guest to retrieve the item, and does a happy wiggle when the lid closes. The team debated the wiggle extensively, but the Decider approved it. + +**Thursday:** The team could not prototype a physical robot interaction digitally, so they used a Wizard of Oz approach: they programmed the actual Relay robot with the new behaviors and prepared to have real guests interact with it at a partner hotel. + +**Friday:** Instead of a standard screen-based prototype test, the team set up at a hotel. 5 guests who had called the front desk for items were surprised by the robot delivery. The team observed from the security camera feed and debriefed guests immediately after. All 5 guests smiled or laughed when the robot arrived. 4 out of 5 pulled out their phones to take a photo or video. The wiggle generated the strongest positive reaction, with 3 guests saying "That's adorable" or similar. 0 guests expressed discomfort or concern. + +### Results + +Savioke refined the interaction based on the sprint findings and deployed Relay in multiple hotel chains. The wiggle became a signature behavior. Hotels reported that robot deliveries generated social media posts from guests, providing free marketing. + +### Lessons + +- Physical product sprints can use Wizard of Oz prototyping instead of screen mockups +- Emotional design details (the wiggle) can be the difference between a gimmick and a beloved experience +- Testing in context (a real hotel, not a lab) provided higher-quality reactions +- The sprint question was answered definitively in one day: guests love robot delivery + +## Case Study 4: Flatiron Health - Cancer Research Data + +### Company + +Flatiron Health, a healthcare technology company building software to organize cancer research data from electronic health records. Their users were oncologists and clinical researchers. + +### Challenge + +Oncologists needed to find eligible patients for clinical trials, but the process involved manually searching through medical records. Flatiron had the data but the interface was designed for data scientists, not doctors. The sprint question: "Can we build a clinical trial matching tool that oncologists will actually use during patient appointments?" + +### Sprint Process + +**Monday:** The team included two oncologists, a data scientist, a designer, and a product manager. The expert interviews revealed that oncologists have approximately 15 minutes per patient appointment and will not use any tool that takes more than 30 seconds to deliver a result. The target: the moment when an oncologist wonders "Is there a clinical trial for this patient?" + +**Tuesday:** Lightning Demos included how Google Flights shows results instantly with progressive detail, how dating apps use simple yes/no swiping to reduce decision fatigue, and how an existing internal tool (complex but accurate) surfaced matches. Sketches ranged from a fully automated notification system to a single-search-box interface. + +**Wednesday:** The winning sketch was a "one-click match" concept: the oncologist clicks a button next to the patient's name in the EHR, and within seconds sees a ranked list of eligible trials with a confidence score and one-line summary for each. + +**Thursday:** The team built a Figma prototype with realistic patient data (anonymized). They created 3 patient scenarios with pre-populated trial results. The prototype looked like it was embedded in the existing EHR interface, which was critical for realism. + +**Friday:** 5 oncologists tested the prototype between real patient appointments. All 5 understood the interface immediately. 4 out of 5 said they would use it during appointments. The key finding: oncologists cared more about the "why" (why this patient matches this trial) than the "what" (which trials matched). The confidence score was not sufficient; they needed to see the specific matching criteria. + +### Results + +Flatiron redesigned the matching display to show specific eligibility criteria alongside each trial recommendation. The tool was launched as part of their clinical platform and increased clinical trial enrollment rates at partner hospitals. + +### Lessons + +- Domain experts (oncologists) on the sprint team prevented the designers from building something technically elegant but clinically useless +- The constraint of 30 seconds per interaction forced ruthless simplicity +- The sprint revealed a critical insight (show "why" not just "what") that would have taken months to discover through traditional development + +## Case Study 5: Harvest - Time Tracking for Freelancers + +### Company + +Harvest, a time tracking and invoicing tool. They noticed that freelancers signed up but abandoned the product before sending their first invoice. + +### Challenge + +Freelancers found time tracking tedious and rarely did it consistently. Without tracked time, they could not generate invoices, which was the product's core value. The sprint question: "Can we make time tracking effortless enough that freelancers actually do it every day?" + +### Sprint Process + +**Monday:** The team mapped the freelancer's day from waking up to sending an end-of-month invoice. They discovered that freelancers did not think in terms of "projects" and "time entries" (Harvest's mental model) but in terms of "clients" and "what I did today." The target: the daily habit of recording time. + +**Tuesday:** Lightning Demos included how fitness apps use daily streaks to build habits, how Uber shows a trip summary after each ride (passive time tracking), and how journaling apps prompt reflection at the end of the day. The team sketched solutions including an end-of-day prompt, automatic time detection from calendar events, and a simplified mobile interface. + +**Wednesday:** The Decider chose a "daily digest" concept: at 5 PM, Harvest sends a notification that says "What did you work on today?" The freelancer taps to see their calendar events pre-filled as time entries. They confirm, adjust, or add entries in under 60 seconds. + +**Thursday:** The prototype was a series of mobile screens in Figma showing the notification, the pre-filled daily digest, and the one-tap confirmation flow. The Writer created realistic calendar data for a fictional freelance designer. + +**Friday:** 5 freelancers tested the prototype. All 5 said the end-of-day prompt was significantly better than opening the app and manually starting timers. 3 out of 5 said the pre-filled entries from calendar data would save them the most time. The biggest complaint: 2 out of 5 did not use a calendar for all their work, so the pre-fill was incomplete. + +### Results + +Harvest launched a simplified end-of-day tracking feature that reduced the average time-tracking effort from 5 minutes per day to under 1 minute. Calendar integration became a premium feature. + +### Lessons + +- The product's mental model (projects, time entries) did not match the user's mental model (clients, what I did today) +- Passive data collection (calendar events) dramatically reduced user effort +- The sprint revealed that the core problem was not the interface but the workflow: users needed a prompt, not a better stopwatch + +## Case Study 6: Code for America - Government Benefits Application + +### Company + +Code for America, a nonprofit that works with government agencies to improve public services through technology. They were redesigning the application process for government benefits (food assistance, healthcare, childcare subsidies). + +### Challenge + +The existing application form was 40 pages long, required documentation that applicants often did not have, and took an average of 3 hours to complete. Many eligible people abandoned the application. The sprint question: "Can we reduce the application from 3 hours to under 20 minutes while still collecting the information the government needs?" + +### Sprint Process + +**Monday:** The team included a benefits caseworker, a policy expert, two designers, and a developer. Expert interviews revealed that 60% of form fields were either redundant, rarely used for eligibility determination, or could be verified through existing government databases. The target: the first 10 minutes of the application, which had the highest abandonment rate. + +**Tuesday:** Lightning Demos included how TurboTax turns a complex tax form into a conversational Q&A, how UK.gov reduced government forms to plain language, and how mobile banking apps use progressive disclosure. Sketches included a chatbot-style application, a "tell us about yourself" conversational form, and a staged approach that collects only essential information first. + +**Wednesday:** The winning concept was a staged application: Stage 1 collects only what is needed for a preliminary eligibility check (5 questions), Stage 2 completes the full application only if the applicant qualifies. This meant applicants who were not eligible learned within 2 minutes instead of investing 3 hours. + +**Thursday:** The team built a mobile-first prototype with clear, plain-language questions, large buttons, and a progress indicator. They included a Spanish language option for 3 of the 5 screens. + +**Friday:** 5 participants were recruited from a community center that assists benefits applicants. 4 out of 5 completed Stage 1 in under 3 minutes. All 5 said the language was clearer than the existing form. 3 out of 5 expressed relief at learning their eligibility early: "I wish all government forms started by telling you if you qualify." 1 participant who was not tech-savvy needed help navigating the mobile interface. + +### Results + +The staged application approach was adopted by several counties in California. Initial data showed a 40% reduction in application abandonment and a 25% increase in completed applications. + +### Lessons + +- Government services benefit enormously from design sprints because the user experience is often decades behind the private sector +- Involving a policy expert on the sprint team prevented the designers from cutting fields that were legally required +- The biggest insight was structural (staged vs. linear) not visual (better buttons or colors) +- Testing with actual benefits applicants (not proxies) was essential for realistic feedback + +## Case Study 7: Grind Coffee - Subscription Model + +### Company + +Grind, a London-based coffee company with physical cafes exploring a direct-to-consumer subscription for home coffee delivery. + +### Challenge + +Grind had strong brand recognition from their cafes but no online subscription presence. They did not know if their cafe customers would pay for a home delivery subscription or what the subscription experience should look like. The sprint question: "Will Grind cafe customers subscribe to home coffee delivery, and what do they need to see to commit?" + +### Sprint Process + +**Monday:** The team mapped two journeys: the existing cafe visit and the hypothetical subscription sign-up. They discovered that cafe loyalty was emotional (community, baristas, atmosphere) while subscription would need to be practical (convenience, freshness, value). The target: the subscription landing page where a cafe customer decides whether to subscribe. + +**Tuesday:** Lightning Demos included Dollar Shave Club's viral landing page, how Nespresso creates a luxury unboxing experience, and how HelloFresh explains subscription flexibility (skip, pause, cancel). Solution sketches explored different value propositions: freshness guarantee, exclusive blends, customization, and environmental impact. + +**Wednesday:** The Decider chose a landing page concept that led with freshness ("Roasted on Monday, at your door by Wednesday") combined with a simple quiz to match the customer's taste profile. The key differentiator: each delivery would include a handwritten-style note from the roaster. + +**Thursday:** The team built a Keynote click-through prototype of the landing page, taste quiz, subscription configuration (frequency, grind type, quantity), and confirmation page. They used real product photography from Grind's existing marketing materials. + +**Friday:** 5 Grind cafe regulars tested the prototype. All 5 understood the value proposition immediately. 4 out of 5 said they would subscribe. The freshness angle ("roasted on Monday") was the most compelling element, cited by all 5 participants. The roaster's note was cited by 3 out of 5 as a differentiator from generic subscriptions. Pricing was the main concern: 2 participants said they would need to see a clear comparison to their current cafe spending. + +### Results + +Grind launched their subscription service using the freshness-first messaging and taste quiz validated in the sprint. The subscription business grew to become a significant revenue stream alongside their physical cafes. + +### Lessons + +- Existing customers are the best first audience for a new product line, but their motivations may differ from what the team assumes +- A concrete detail ("roasted on Monday, at your door by Wednesday") is more persuasive than an abstract claim ("fresh coffee delivered") +- The sprint identified a gap (pricing comparison) that the team had not considered, leading them to add a "cost per cup" calculator to the final landing page + +## Cross-Cutting Patterns + +Looking across all seven case studies, several patterns emerge: + +### The Target Is Rarely Where You Expect + +In 5 out of 7 cases, the Monday target ended up in a different part of the journey than the team initially expected. Slack thought the problem was in-app onboarding; it was in the invitation email. Harvest thought the problem was the timer UI; it was the daily workflow. + +### Simplicity Wins + +Every successful sprint prototype was simpler than the team's initial instinct. Flatiron went from a complex dashboard to a one-click button. Code for America went from a 40-page form to 5 questions. The design sprint's time constraint forces simplicity. + +### Friday Reveals Surprises + +In every case, at least one significant Friday finding was unexpected. Savioke did not expect the wiggle to be the standout feature. Flatiron did not expect oncologists to prioritize "why" over "what." Blue Bottle did not expect customers to pay a premium based on quiz-driven confidence. + +### Domain Experts Are Essential + +The most successful sprints (Flatiron, Code for America) included domain experts as full team members, not just Monday interviewees. Their constraints and insights prevented the team from designing solutions that were technically elegant but practically useless. + +### Real Users, Real Context + +Savioke tested in a real hotel. Code for America recruited from a community center. The closer the test environment matches reality, the more reliable the results. + +### One Week Is Enough + +Every team started the sprint week doubting they could prototype and test in 5 days. Every team ended the week with actionable insights they would not have had for months under a normal development process. diff --git a/.agents/skills/design-sprint/references/facilitation.md b/.agents/skills/design-sprint/references/facilitation.md new file mode 100644 index 00000000..13115f4d --- /dev/null +++ b/.agents/skills/design-sprint/references/facilitation.md @@ -0,0 +1,316 @@ +# Facilitation Guide for Sprint Masters + +The Sprint Master makes or breaks the design sprint. This role is equal parts timekeeper, therapist, traffic cop, and energy manager. A great facilitator creates the conditions for the team's best thinking while preventing the dysfunction that derails most group work. + + +## Table of Contents +1. [The Sprint Master Role](#the-sprint-master-role) +2. [Time-Boxing Techniques](#time-boxing-techniques) +3. [Energy Management](#energy-management) +4. [Dealing with Difficult Participants](#dealing-with-difficult-participants) +5. [Decision-Making Protocols](#decision-making-protocols) +6. [Room Setup and Materials Checklist](#room-setup-and-materials-checklist) +7. [Day-by-Day Facilitation Tips](#day-by-day-facilitation-tips) +8. [Logistics: Music, Snacks, and Breaks](#logistics-music-snacks-and-breaks) + +--- + +## The Sprint Master Role + +### Core Responsibilities + +| Responsibility | What It Looks Like | +|---------------|-------------------| +| Time management | Starting and ending exercises on time, using visible timers | +| Process enforcement | Ensuring each exercise follows the correct format | +| Energy management | Reading the room, calling breaks, adjusting pace | +| Neutrality | Not advocating for any particular solution | +| Conflict resolution | Defusing tension without taking sides | +| Documentation | Ensuring all outputs are captured (photos, notes) | +| Logistics | Room setup, supplies, meals, technology | + +### Who Should Be the Sprint Master + +**Good candidates:** +- Product manager with facilitation experience +- Design lead who can resist designing during the sprint +- External facilitator or consultant +- Scrum master or agile coach + +**Poor candidates:** +- The CEO or founder (they should be the Decider, not the facilitator) +- Someone who has a strong opinion about the solution (they will push it) +- The most junior person in the room (they lack the authority to enforce time) +- Someone who has never run a meeting before (start smaller) + +### Key Principle: The Sprint Master Does Not Contribute Solutions + +During sketching, voting, and deciding, the Sprint Master participates only as a facilitator. If they have a strong solution idea, they should sketch it like everyone else but not advocate for it during critique. The moment a facilitator pushes their own idea, they lose neutrality and the team defers to them. + +## Time-Boxing Techniques + +### Why Time-Boxing Matters + +Without time limits, every exercise expands to fill the available time. Long-term goal becomes a 2-hour strategy debate. Lightning Demos become 15-minute presentations. The storyboard never finishes. + +### Tools for Time-Boxing + +| Tool | When to Use | +|------|------------| +| Time Timer (visual countdown) | Every exercise. Place it where everyone can see it | +| Phone timer with loud alarm | Backup timer. Set it 1 minute before the end as a warning | +| Music playlist | Play during silent work. When the music stops, time is up | +| Written schedule on wall | Post the full day schedule so everyone can see what is coming | + +### The Two-Minute Warning + +For every exercise, announce "Two minutes remaining" when the timer hits the mark. This gives people time to wrap up their thought without the jarring surprise of a sudden stop. + +### When to Extend Time + +Extend time only when: +- The team is clearly making productive progress (not just talking) +- The exercise output is incomplete and critical for the next step +- The Decider explicitly asks for more time + +Never extend time because: +- The discussion is "interesting" (interesting discussions are infinite) +- One person is not finished (they can catch up during the break) +- The team "wants to explore this more" (the schedule exists for a reason) + +### Time-Boxing by Day + +**Monday:** + +| Exercise | Budgeted Time | Strict or Flexible | +|----------|--------------|-------------------| +| Long-term goal | 30 min | Strict. The Decider breaks ties | +| Sprint questions | 45 min | Flexible +15 min if new questions are emerging | +| Customer journey map | 60 min | Strict. Keep the map simple | +| Ask the Experts | 20 min per expert | Strict. Thank the expert and move on | +| HMW voting | 30 min | Strict. Voting should not require discussion | +| Target selection | 30 min | Strict. Decider makes the call | + +**Tuesday:** + +| Exercise | Budgeted Time | Strict or Flexible | +|----------|--------------|-------------------| +| Lightning Demos | 3 min per demo | Strict. Use a timer for each demo | +| Notes | 20 min | Strict | +| Ideas | 20 min | Strict | +| Crazy 8s | 8 min | Strict. 1 minute per panel, no exceptions | +| Solution Sketch | 90 min | Flexible +15 min. This is the most important output | + +**Wednesday:** + +| Exercise | Budgeted Time | Strict or Flexible | +|----------|--------------|-------------------| +| Art Museum | 30 min | Strict | +| Speed Critique | 3 min per sketch | Strict. Use a timer for each sketch | +| Straw Poll | 15 min | Strict | +| Supervote | 15 min | Strict. The Decider knows what they want | +| Storyboard | 150 min | Flexible +30 min if gaps remain | + +**Thursday:** + +| Exercise | Budgeted Time | Strict or Flexible | +|----------|--------------|-------------------| +| Role assignment | 30 min | Strict | +| Building | 150 min | Flexible. Prioritize completion over polish | +| Stitching | 90 min | Strict. Must finish to allow trial run | +| Team review | 30 min | Strict | +| Trial run | 30 min | Strict. Must happen before end of day | + +**Friday:** + +| Exercise | Budgeted Time | Strict or Flexible | +|----------|--------------|-------------------| +| Each interview | 45 min | Strict. Respect participant's time | +| Between-interview breaks | 30 min | Flexible. Can shorten to 15 if running late | +| Debrief | 75 min | Flexible +30 min. This is the payoff | + +## Energy Management + +### Energy Management Tactics + +| Tactic | When to Use | +|--------|------------| +| Stand-up exercises | After lunch, during storyboarding, any time energy drops | +| Change of scenery | Take a 10-minute walk break outside the sprint room | +| Music during silent work | Background music keeps energy up during individual exercises | +| Snack table | Protein-heavy snacks available all day (avoid sugar crashes) | +| Celebrate small wins | End each day by naming what the team accomplished | +| Physical movement | Move to a different wall, rearrange chairs, change the room layout | + +### Afternoon Slump Protocol + +Every day between 2:00 and 3:00 PM, energy typically drops. Plan for it: + +1. Schedule a 10-minute break at 2:00 PM +2. Provide coffee and high-protein snacks +3. Start the next exercise with a brief standing activity +4. If possible, schedule active exercises (voting, building) for this time slot rather than passive ones (listening, reviewing) + +## Dealing with Difficult Participants + +### The HiPPO (Highest-Paid Person's Opinion) + +**Behavior:** Dominates discussion, others defer to their authority. +**Tactic:** Use the structured exercises as designed. Silent voting, anonymous sketches, and individual work prevent the HiPPO from overriding the group. If the HiPPO is the Decider, remind them that their power comes at the Supervote, not during open discussion. + +### The Skeptic + +**Behavior:** Vocally doubts the process. "This is a waste of time." "This will never work." +**Tactic:** Acknowledge their concern briefly: "I hear you. Let's see how the week goes. If we are not getting value by Wednesday, we can adjust." Then redirect to the exercise. Most skeptics become converts by Wednesday when they see the storyboard take shape. + +### The Talker + +**Behavior:** Fills every silence with commentary. Derails exercises with tangents. +**Tactic:** Use the timer as your ally: "We have 2 minutes left, so let's get back to the exercise." During silent phases, gently say "Remember, this part is individual and quiet." If needed, speak privately during a break. + +### The Perfectionist + +**Behavior:** Cannot move on until every detail is resolved. +**Tactic:** Use the phrase "We will address that later in the sprint" or "Let's note it and move on." Put unresolved details on a parking lot sticky note. The perfectionist needs to see that their concern is captured, even if it is not resolved now. + +### The Quiet Participant + +**Behavior:** Rarely speaks up, defers to others, may seem disengaged. +**Tactic:** The sprint's silent exercises (sketching, dot voting) naturally give quiet people a voice. During discussions, use round-robin: "Let's hear from everyone. [Name], what do you think?" During breaks, check in privately: "How is it going? Anything you want to raise?" + +### The Multi-Tasker + +**Behavior:** Checks phone, works on email, takes calls during the sprint. +**Tactic:** Set the rule on Monday morning: no devices during exercises. Place a phone basket at the door. If someone violates, say "Let's put phones away for this exercise. We have a break in 30 minutes." If they persist, talk privately during a break about the commitment. + +## Decision-Making Protocols + +### When the Team Decides + +Dot voting and straw polls are used for: +- HMW prioritization +- Art Museum heat maps +- Straw poll preferences + +These are input for the Decider, not final decisions. + +### When the Decider Decides + +The Decider has final authority on: +- Long-term goal +- Target selection +- Supervote (which solution to prototype) +- Rumble vs All-in-One +- Any tie-breaking situation + +### When the Sprint Master Decides + +The Sprint Master has authority over: +- Time management (when to end an exercise) +- Process (which exercise comes next) +- Room logistics +- Whether to extend time on an exercise + +## Room Setup and Materials Checklist + +### Room Requirements + +- [ ] Large room with floor-to-ceiling whiteboard (or multiple whiteboards) +- [ ] No glass walls (privacy for discussions) +- [ ] Door that closes (quiet from outside noise) +- [ ] Power outlets for laptops (Thursday prototyping) +- [ ] Separate observation room for Friday (or a quiet corner with headphones) + +### Materials Checklist + +**Writing and drawing:** +- [ ] Thick black markers (Sharpie or similar), 1 per person +- [ ] Fine-tip markers for detail work, 1 per person +- [ ] Letter-size blank paper, 50+ sheets +- [ ] Whiteboard markers (black, blue, red, green) +- [ ] Whiteboard eraser and spray + +**Sticky notes and voting:** +- [ ] Standard sticky notes (3x3), 5 pads in various colors +- [ ] Large sticky notes (5x8), 2 pads +- [ ] Small dot stickers (1/4 inch), 100+ +- [ ] Large dot stickers (3/4 inch), 2 per person plus 3 for the Decider +- [ ] Painter's tape for hanging sketches + +**Technology:** +- [ ] Time Timer or visible countdown timer +- [ ] Laptop for Thursday prototyping +- [ ] TV or monitor for Friday interview observation +- [ ] Video conferencing setup if remote participants join for Friday +- [ ] Camera for recording Friday interviews + +**Comfort:** +- [ ] Snacks: nuts, fruit, protein bars, crackers +- [ ] Drinks: water, coffee, tea +- [ ] Lunch plan for each day (order in or nearby restaurant with fast service) + +## Day-by-Day Facilitation Tips + +### Monday + +- Start with introductions if not everyone knows each other +- Write the schedule on the whiteboard so everyone sees the plan +- Enforce the "no solutions yet" rule: Monday is about understanding, not solving +- Take a photo of every whiteboard before erasing +- End the day by reading the target aloud and getting a verbal confirmation from everyone + +### Tuesday + +- Begin with a recap of Monday's target (2 minutes) +- Keep Lightning Demos moving fast; use the timer visibly +- During the Four-Step Sketch, your job is to keep the room silent +- Walk around during Crazy 8s and say "Switch" every minute +- Collect sketches at the end without looking at them + +### Wednesday + +- Arrive early to tape sketches to the wall for the Art Museum +- During Speed Critique, stand next to each sketch and point as you narrate +- Keep a running list of standout ideas on the whiteboard +- After the Supervote, thank the team for their work and honor the Decider's choice +- During storyboarding, ask "What happens next?" to keep the team moving + +### Thursday + +- Do a quick standing check-in at 10:30, 12:00, and 2:00 +- Walk around and look at progress; flag problems early +- Protect the Interviewer's time for script writing +- Insist on the trial run even if the team resists + +### Friday + +- Arrive 30 minutes early to set up rooms +- Brief the team: "Watch, listen, and take notes. Do not react out loud." +- Between interviews, lead a 5-minute "What did we see?" discussion +- At the debrief, write findings on the whiteboard as the team discusses +- End the sprint by thanking the team and scheduling a follow-up meeting + +## Logistics: Music, Snacks, and Breaks + +### Music + +- Play low-volume instrumental music during silent work phases (sketching, dot voting) +- No lyrics (they distract from thinking) +- Good options: lo-fi beats, jazz, ambient electronic, classical +- Turn music off during discussions and presentations + +### Breaks + +| Type | Frequency | Duration | +|------|-----------|----------| +| Micro break | Every 60-90 min | 5 min (stand, stretch, refill water) | +| Full break | Mid-morning and mid-afternoon | 15 min (leave the room, check phone) | +| Lunch | Daily | 45-60 min (eat away from the sprint room if possible) | + +### End-of-Day Rituals + +End each day with: +1. Sprint Master reads aloud what was accomplished +2. Quick round: each person names one thing they are excited about +3. Confirm tomorrow's start time +4. Remind everyone: no outside work on sprint topics tonight (fresh eyes matter) diff --git a/.agents/skills/design-sprint/references/friday.md b/.agents/skills/design-sprint/references/friday.md new file mode 100644 index 00000000..e8425db0 --- /dev/null +++ b/.agents/skills/design-sprint/references/friday.md @@ -0,0 +1,316 @@ +# Friday: Test with Real Users + +Friday is the payoff. Five customers interact with the prototype while the team watches, listens, and takes notes. By the end of the day, the team will have clear evidence of what works, what fails, and what to do next. The quality of Friday depends entirely on the quality of the interviews and the discipline of the observation. + + +## Table of Contents +1. [Schedule Overview](#schedule-overview) +2. [The Five-Act Interview Script](#the-five-act-interview-script) +3. [Interviewer Techniques](#interviewer-techniques) +4. [Observation Room Setup](#observation-room-setup) +5. [Pattern Recognition](#pattern-recognition) +6. [End-of-Sprint Debrief](#end-of-sprint-debrief) +7. [Templates](#templates) +8. [Common Friday Mistakes](#common-friday-mistakes) + +--- + +## Schedule Overview + +| Time | Activity | Duration | +|------|----------|----------| +| 9:00 - 9:30 | Setup interview and observation rooms | 30 min | +| 9:30 - 9:45 | Interviewer warm-up and team briefing | 15 min | +| 9:45 - 10:30 | Interview 1 | 45 min | +| 10:30 - 11:00 | Break and team discussion | 30 min | +| 11:00 - 11:45 | Interview 2 | 45 min | +| 11:45 - 12:15 | Break and team discussion | 30 min | +| 12:15 - 1:00 | Interview 3 | 45 min | +| 1:00 - 1:45 | Lunch | 45 min | +| 1:45 - 2:30 | Interview 4 | 45 min | +| 2:30 - 3:00 | Break and team discussion | 30 min | +| 3:00 - 3:45 | Interview 5 | 45 min | +| 3:45 - 5:00 | Pattern recognition and debrief | 75 min | + +## The Five-Act Interview Script + +### Act 1: Friendly Welcome (5 minutes) + +**Goal:** Make the participant comfortable, set expectations, get consent. + +**Script:** + +"Hi, thanks for coming in today. My name is [name] and I will be walking you through some things we are working on. Before we begin, I want to make sure you know there are no right or wrong answers. We are testing the product, not you. If something is confusing, that is our fault, not yours. + +I am going to ask you to think aloud as you go. Just tell me what you are looking at, what you are trying to do, and what you are thinking. This is really helpful for us. + +We have a few people from the team watching in another room so they can hear your feedback directly. And with your permission, we would like to record the session so we can review it later. Is that okay? + +Great. Do you have any questions before we start?" + +### Act 2: Context Questions (5 minutes) + +**Goal:** Understand the participant's background, current behavior, and mindset before showing the prototype. + +**Example questions by product type:** + +| Product Type | Context Questions | +|-------------|-------------------| +| Project management tool | "Tell me about how you currently keep track of projects at work. What tools do you use? What is frustrating about your current setup?" | +| E-commerce | "When was the last time you bought [category] online? Walk me through how you found and chose what to buy." | +| Healthcare app | "How do you currently manage your [condition]? What does a typical week look like?" | +| B2B platform | "Tell me about your role. When you need to [task], how do you handle that today?" | + +### Act 3: Introduce the Prototype (5 minutes) + +**Goal:** Show the entry point and observe the first impression without explaining anything. + +**Script:** + +"Now I am going to show you something we have been working on. Some parts might work, some might not. That is totally normal. I did not design this, so please be honest. You will not hurt my feelings. + +[Show the first screen of the prototype] + +Take a look at this. Without clicking anything, tell me: what is this? What do you think you can do here? Who do you think this is for?" + +**Critical rule:** Do not explain the prototype. If they are confused, that is data. Let the silence sit. Resist the urge to help. + +### Act 4: Tasks and Nudges (15 minutes) + +**Goal:** Watch the participant attempt realistic tasks with the prototype. + +**Setting up tasks:** + +"Great. Now I would like you to try a few things. Remember, think aloud as you go." + +**Task format:** + +Use scenario-based tasks, not instructions: + +| Weak Task (Avoid) | Strong Task (Use) | +|-------------------|-------------------| +| "Click the signup button" | "You heard about this from a friend and want to try it" | +| "Go to the pricing page" | "You are interested but need to figure out if it fits your budget" | +| "Create a new project" | "You just joined this tool and want to set up your first project for your marketing team" | +| "Find the search bar" | "You are looking for a specific type of [product]. How would you find it?" | + +**Nudge techniques when the participant gets stuck:** + +| Situation | Nudge | +|-----------|-------| +| Participant goes silent | "What are you thinking right now?" | +| Participant is stuck | "What would you expect to happen?" | +| Participant asks for help | "What would you try if I were not here?" | +| Participant clicks a dead end | "Interesting. In a real version, that would work. For now, let me take you to the next screen." | +| Participant goes off the path | "That is great feedback. For the next task, let me show you this screen." | + +### Act 5: Debrief (5 minutes) + +**Goal:** Capture the participant's overall impressions and ask targeted follow-up questions. + +**Debrief questions:** + +1. "What was your overall impression?" +2. "What stood out to you, either positively or negatively?" +3. "Who do you think this is for?" +4. "Would you use this? Why or why not?" +5. "How does this compare to what you use today?" +6. "If you could change one thing, what would it be?" + +Also ask follow-up questions tied to your specific sprint questions. Close by asking if there is anything else they would like to share and thanking them for their time. + +## Interviewer Techniques + +### Staying Neutral + +| Do | Do Not | +|----|--------| +| Nod and say "mm-hmm" | Say "great job" or "that is right" | +| Ask "tell me more about that" | Say "actually, you are supposed to click here" | +| Pause and let silence work | Fill silence with explanations | +| Mirror their words: "You said it felt confusing?" | Defend the design: "Well, the idea is that..." | +| Take notes on a pad | Type loudly on a laptop | + +### The Power of Silence + +When a participant pauses, wait at least 5 seconds before speaking. Most people will fill the silence with their thoughts, which are the most valuable data you can collect. + +### Handling Difficult Moments + +| Moment | Response | +|--------|----------| +| Participant says "I hate this" | "Tell me more. What specifically is not working for you?" | +| Participant gives only positive feedback | "If a friend asked you about this, what would you warn them about?" | +| Participant asks "Am I doing this right?" | "There is no right or wrong. What would you try?" | +| Participant is clearly frustrated | "I can see this is frustrating. That is really useful feedback. Let's move to the next thing." | +| Participant finishes too quickly | "Let's go back to [screen]. What were you thinking when you saw this?" | + +## Observation Room Setup + +### The Note-Taking Grid + +Draw this on the whiteboard before the first interview: + +``` + | Customer 1 | Customer 2 | Customer 3 | Customer 4 | Customer 5 | +|---------------|------------|------------|------------|------------|------------| +| First impression | | | | | | +| [Screen/Task 1] | | | | | | +| [Screen/Task 2] | | | | | | +| [Screen/Task 3] | | | | | | +| [Key question 1] | | | | | | +| [Key question 2] | | | | | | +| Overall reaction | | | | | | +``` + +**Row labels** come from the storyboard frames and sprint questions. Add 7-10 rows that correspond to the key moments you want to test. + +### How to Take Notes + +1. Each team member writes observations on sticky notes during the interview +2. Use one color per team member (so you can trace who observed what) +3. After each interview, place sticky notes in the appropriate grid cell +4. Mark each note with a symbol: + - **Checkmark** for positive reactions, successful completions, or enthusiastic comments + - **X** for negative reactions, failures, confusion, or complaints + - **Tilde (~)** for neutral, mixed, or ambiguous reactions + +## Pattern Recognition + +### After All Five Interviews + +1. Step back and look at the entire grid +2. Read across each row: do you see mostly checkmarks, mostly Xs, or a mix? +3. Highlight rows with strong patterns (4-5 of the same symbol) + +### Pattern Categories + +| Pattern | What It Means | Example | +|---------|--------------|---------| +| 5 checkmarks | Strong validation. This works | All 5 users understood the pricing immediately | +| 4 checkmarks, 1 X | Mostly works, investigate the outlier | 4 of 5 completed onboarding, 1 got stuck on step 3 | +| 3 checkmarks, 2 Xs | Mixed signal, needs refinement | Some users loved the AI suggestions, others did not trust them | +| 2 checkmarks, 3 Xs | Significant problem | Most users could not find the search function | +| 5 Xs | Clear failure. This does not work | Nobody understood the value proposition on the landing page | +| All tildes | Indifference (arguably worse than failure) | Users did not care about the feature either way | + +### Minimum Viable Signal + +- **3 out of 5** participants showing the same pattern is a meaningful signal +- **5 out of 5** is a strong signal that demands action +- **2 out of 5** is inconclusive and may require further testing + +## End-of-Sprint Debrief + +### Step 1: Review Sprint Questions (15 minutes) + +Return to Monday's sprint questions. For each one: + +1. Read the question aloud +2. Review the evidence from the grid +3. Determine the answer: Yes, No, Partially, or Inconclusive + +**Template:** + +``` +Sprint Question: Will first-time users understand what our product does? +Evidence: 4/5 correctly described the product on first impression. 1 was confused by the headline. +Answer: Yes, with minor copy improvements needed. +``` + +### Step 2: Categorize Findings (20 minutes) + +Organize all observations into three columns on the whiteboard: + +**What Worked (keep and build on):** +- List specific screens, features, or copy that received consistent positive feedback +- Include direct quotes from participants + +**What Failed (fix or remove):** +- List specific moments of confusion, frustration, or failure +- Note whether the failure was universal (5/5) or partial (3/5) + +**Mixed Results (investigate further):** +- List elements with split reactions +- Note possible explanations for the split + +### Step 3: Decide Next Steps (20 minutes) + +| Friday Result | Recommended Next Step | +|--------------|----------------------| +| Core concept validated, minor issues | Build the product. Fix the specific issues identified | +| Core concept validated, major UX issues | Run a follow-up sprint focused on the problematic areas | +| Two concepts tested (Rumble), one won | Build the winner. Document why the other lost | +| Core concept failed, but insights gained | Pivot and run another sprint with a new approach | +| Everything failed | Go back to Monday. Redefine the problem. The week saved you months | +| Inconclusive results | Recruit 5 more users and test again, or rewrite the tasks | + +## Templates + +### Interview Notes Template (Per Participant) + +``` +Participant: #[number] Date/Time: [date, time] + +FIRST IMPRESSION +What they said: +Understood the product: [ ] Yes [ ] No [ ] Partially + +TASK 1: [Description] +Completed: [ ] Yes [ ] No [ ] With help +Notable quotes: + +TASK 2: [Description] +Completed: [ ] Yes [ ] No [ ] With help +Notable quotes: + +OVERALL DEBRIEF +Would they use this: [ ] Yes [ ] No [ ] Maybe +Key quote: +``` + +### Sprint Results Summary Template + +``` +SPRINT: [Name] DATE: [Week of] TARGET: [Monday's target] + +SPRINT QUESTIONS AND ANSWERS: +1. [Question] → [Answer with evidence] +2. [Question] → [Answer with evidence] +3. [Question] → [Answer with evidence] + +WHAT WORKED: WHAT FAILED: +- [Finding 1] - [Finding 1] +- [Finding 2] - [Finding 2] + +NEXT STEPS: +- [ ] [Action item 1] — Owner: [Name] — Due: [Date] +- [ ] [Action item 2] — Owner: [Name] — Due: [Date] +``` + +## Common Friday Mistakes + +### The Interviewer Explains the Prototype + +**Problem:** When a user gets confused, the interviewer says "Oh, this is supposed to be a dashboard where you can..." +**Fix:** Practice the phrase "What would you expect to see here?" Let confusion happen. It is the most valuable data. + +### The Team Watches Passively + +**Problem:** The observation team watches interviews like a movie without taking notes. +**Fix:** Require sticky notes. Each person should produce 5-10 notes per interview. The grid on the whiteboard makes note-taking structured and accountable. + +### Skipping the Debrief + +**Problem:** After the last interview, the team is exhausted and says "let's process this next week." +**Fix:** The debrief is the most important hour of the entire sprint. Do it while observations are fresh. Waiting even one weekend degrades the team's memory and enthusiasm. + +### Recruiting the Wrong Users + +**Problem:** The team tests with colleagues, friends, or people who do not match the target customer. +**Fix:** Use a screener survey. Recruit people who match the customer profile defined on Monday. Test with strangers who have no loyalty to the team. + +### Over-Indexing on One Participant + +**Problem:** One user gave dramatic negative feedback and the team panics. +**Fix:** Wait for patterns. One negative reaction out of five may be an outlier. Three negative reactions out of five is a real signal. diff --git a/.agents/skills/design-sprint/references/monday.md b/.agents/skills/design-sprint/references/monday.md new file mode 100644 index 00000000..d3af0e06 --- /dev/null +++ b/.agents/skills/design-sprint/references/monday.md @@ -0,0 +1,278 @@ +# Monday: Map the Problem + +Monday sets the foundation for the entire sprint. By the end of the day, the team will have a shared understanding of the problem, a map of the customer journey, and a clear target for the week. Every minute counts: poor Monday execution means the rest of the sprint drifts without direction. + +## Schedule Overview + +| Time | Exercise | Duration | +|------|----------|----------| +| 10:00 - 10:15 | Welcome and ground rules | 15 min | +| 10:15 - 10:45 | Long-term goal | 30 min | +| 10:45 - 11:30 | Sprint questions | 45 min | +| 11:30 - 12:30 | Customer journey map | 60 min | +| 12:30 - 1:30 | Lunch | 60 min | +| 1:30 - 3:30 | Ask the Experts | 120 min | +| 3:30 - 4:00 | How Might We organization | 30 min | +| 4:00 - 4:30 | Vote on HMWs | 30 min | +| 4:30 - 5:00 | Pick the target | 30 min | + +## Welcome and Ground Rules + +Before starting, the Sprint Master should set expectations for the week: + +- No laptops or phones during exercises (breaks are fine) +- Silence during individual work phases +- The Decider has final say on all tie-breaking votes +- Timers are strict: when the bell rings, pencils down +- Write on sticky notes in thick marker so everyone can read from a distance +- Every voice matters, but talking happens in structured turns + +## Long-Term Goal Exercise + +### Purpose + +Align the team on what success looks like. The long-term goal creates a north star that keeps every subsequent decision anchored. + +### How to Facilitate + +1. Hand everyone a sheet of paper +2. Ask: "Imagine it is two years from now. Our sprint was a massive success. What changed? What is true about our product, company, or customers?" +3. Give 5 minutes for individual writing (silence) +4. Go around the room. Each person reads their goal aloud +5. Sprint Master writes each goal on the whiteboard +6. Discuss for 10 minutes: where do we agree, where do we disagree? +7. The Decider picks one goal or combines two + +### Example Long-Term Goals + +| Company Type | Long-Term Goal | +|-------------|----------------| +| B2B SaaS | "Enterprise customers renew their contracts at 95%+ because the product is indispensable to their daily workflow" | +| E-commerce | "First-time buyers come back within 30 days and recommend us to friends" | +| Healthcare | "Patients manage their chronic conditions without needing to call the clinic" | +| Fintech | "Users trust us enough to consolidate all their finances in one place" | +| Education | "Students complete the full course and can demonstrate the skill in a real job" | + +### What Makes a Good Goal + +- Focuses on the customer, not internal metrics +- Describes a changed behavior or belief +- Is ambitious but plausible in 2 years +- Can be broken into testable assumptions + +## Sprint Questions Exercise + +### Purpose + +Surface the risks, assumptions, and unknowns that could prevent the long-term goal. Sprint questions flip optimism into productive skepticism. + +### How to Facilitate + +1. Reframe the prompt: "To reach our goal, what has to be true? What could go wrong? What are we most uncertain about?" +2. Give 5 minutes for individual writing on sticky notes (one question per note) +3. Collect all sticky notes and read them aloud +4. Group similar questions on the whiteboard +5. The team votes (2 dot stickers each) on the most critical questions +6. The Decider selects the top 3 questions for the sprint to address + +### Example Sprint Questions + +- "Will users understand what our product does within 10 seconds of landing on the page?" +- "Can we convince busy professionals to complete a 5-step onboarding flow?" +- "Will customers pay a premium when a free alternative exists?" +- "Do users trust an AI recommendation enough to act on it?" +- "Can non-technical users configure the product without support?" + +### Template + +``` +We believe [assumption]. +If we are wrong, [consequence]. +Sprint question: Will [specific user] actually [specific behavior]? +``` + +## Customer Journey Map + +### Purpose + +Create a shared visual model of how a customer moves from discovery to success. The map becomes the sprint's playing field. + +### Step-by-Step Process + +1. **Draw the frame:** A horizontal line across the whiteboard with "Discovery" on the left and "Success" on the right +2. **List the actors:** Write customer types and key players above the map (e.g., "New user," "Admin," "Sales rep") +3. **Map the steps:** The Sprint Master asks the team to call out each step. Write them left to right as simple boxes connected by arrows +4. **Keep it simple:** Aim for 5-15 steps. If it grows beyond 15, you are going too deep +5. **Use plain language:** "Sees an ad" not "Awareness phase targeting via programmatic display" + +### Example Map: Project Management Tool + +``` +Hears from Visits Watches Signs up Creates Invites First Weekly Upgrades +colleague --> website --> demo --> for free --> project --> team --> meeting --> routine --> to paid + video trial members review +``` + +### Common Mapping Mistakes + +| Mistake | Problem | Fix | +|---------|---------|-----| +| Too many steps | Map becomes unreadable | Merge similar steps, stay at 5-15 | +| Internal process focus | Map shows your workflow, not the customer's | Always start with a customer action | +| Branching paths | Map becomes a flowchart | Pick one primary path; note alternatives as sticky notes | +| Skipping early steps | Map starts at "uses product" | Include how customers discover and evaluate | + +## Ask the Experts + +### Purpose + +Bring specialized knowledge into the room. Experts share what they know so the team operates from facts, not assumptions. + +### Who to Interview + +- **CEO/Founder:** Vision, business constraints, strategic bets +- **Sales/Business Development:** What customers say before buying, common objections +- **Customer Support:** What customers complain about, where they get stuck +- **Engineering Lead:** Technical constraints, what is easy vs. hard to build +- **Marketing:** How customers find the product, messaging that resonates +- **External expert (optional):** Industry analyst, advisor, power user + +### Interview Format + +| Phase | Duration | What Happens | +|-------|----------|-------------| +| Introduction | 2 min | Sprint Master explains what we need from the expert | +| Expert presentation | 10 min | Expert shares their perspective on the challenge | +| Q&A | 10 min | Team asks clarifying questions | +| HMW notes | During all phases | Team writes How Might We notes in real time | + +### Good Questions to Ask Experts + +- "What is the number one reason customers leave?" +- "What do customers say they want that we do not offer?" +- "What surprised you most about how customers use the product?" +- "If you could fix one thing, what would it be?" +- "What would a competitor need to do to beat us?" + +### Tips for the Sprint Master + +- Keep each expert to 20 minutes total +- Gently redirect if the expert goes on tangents +- Remind the team to write HMW notes continuously +- Do not let one expert dominate Monday afternoon + +## How Might We (HMW) Notes + +### Purpose + +Transform problems, insights, and complaints into opportunities. HMW notes reframe negatives as design challenges the team can solve. + +### How to Write HMW Notes + +1. Listen for problems, pain points, and unmet needs during expert interviews +2. Rephrase each one as "How might we...?" on a sticky note +3. Write in thick marker, one idea per note +4. Keep them concise: 5-10 words after "How might we" + +### Conversion Examples + +| What You Hear | HMW Note | +|--------------|----------| +| "Customers never finish onboarding" | HMW make onboarding feel worth completing? | +| "People don't understand our pricing page" | HMW make pricing instantly clear? | +| "Users create an account but never come back" | HMW give users a reason to return on day 2? | +| "Enterprise buyers need approval from 3 people" | HMW help champions sell internally? | +| "Support tickets spike every Monday" | HMW prevent the Monday confusion? | + +### Common HMW Pitfalls + +- **Too broad:** "HMW make the product better?" (not actionable) +- **Too narrow:** "HMW add a tooltip to the settings gear icon?" (already a solution) +- **Contains a solution:** "HMW add a chatbot?" (should be "HMW provide instant answers?") +- **Negative framing:** "HMW stop users from leaving?" (reframe: "HMW make users want to stay?") + +### Organizing and Voting on HMWs + +1. After expert interviews, collect all HMW notes (expect 30-80 notes) +2. Read each one aloud quickly (2-3 seconds each) +3. Organize on the whiteboard by theme (group similar notes together) +4. Place themed groups near the relevant part of the customer journey map +5. Give each person 2 dot stickers +6. Vote silently (no discussion during voting) +7. The Decider gets 4 dot stickers + +## Target Selection + +### Purpose + +Choose the single moment on the customer journey map that the sprint will focus on. Without a target, the team tries to solve everything and solves nothing. + +### How to Select the Target + +1. Review the map with HMW clusters and vote dots visible +2. Look for the intersection of: high risk + high opportunity + answerable in one week +3. The Sprint Master asks: "Given our goal and our sprint questions, where should we focus?" +4. Brief discussion (10 minutes max, not a debate) +5. The Decider makes the final call + +### Target Selection Criteria + +| Criteria | Question to Ask | +|----------|----------------| +| Impact | "If we solve this, does it meaningfully move us toward the long-term goal?" | +| Risk | "Is this the area where we are most uncertain?" | +| Feasibility | "Can we prototype and test a solution for this in 4 days?" | +| Learning | "Will testing this answer our most important sprint question?" | + +### Example Targets + +- "The first 5 minutes after signup: do users understand what to do?" +- "The pricing page: do visitors understand the value and choose a plan?" +- "The handoff from sales demo to first login: do buyers become users?" +- "The weekly report: do managers find it useful enough to keep paying?" + +## Monday Checklist + +Before leaving for the day, confirm: + +- [ ] Long-term goal is written on the whiteboard and agreed upon +- [ ] Top 3 sprint questions are identified and visible +- [ ] Customer journey map is complete (5-15 steps) +- [ ] At least 3 experts have been interviewed +- [ ] HMW notes are organized by theme on the map +- [ ] HMW votes are complete +- [ ] The Decider has chosen a target on the map +- [ ] Everyone knows the target and can explain it +- [ ] Tuesday agenda is confirmed + +## Common Monday Mistakes + +### Spending Too Long on the Goal + +**Problem:** The team debates the long-term goal for 90 minutes, compressing everything else. +**Fix:** Time-box to 30 minutes. The goal does not need to be perfect; it needs to be directional. The Decider breaks ties. + +### Mapping Internal Processes Instead of the Customer Journey + +**Problem:** The map shows "engineering builds feature" and "QA tests" instead of the customer's experience. +**Fix:** Start every step with a customer verb: "Customer sees," "Customer clicks," "Customer decides." + +### Expert Interviews That Turn Into Debates + +**Problem:** The team argues with the expert instead of listening. +**Fix:** Sprint Master enforces a "no debating" rule. The team asks questions and writes HMW notes. Disagreements become sprint questions. + +### Picking a Target That Is Too Broad + +**Problem:** The target is "the entire user experience" or "our go-to-market strategy." +**Fix:** A good target fits on one section of the map. If you cannot prototype and test it in 4 days, narrow it down. + +### Skipping HMW Notes + +**Problem:** The team listens to experts but does not capture opportunities. +**Fix:** Remind the team every 10 minutes to write HMW notes. Provide sticky notes and markers on the table before interviews start. + +### No Decider in the Room + +**Problem:** The person with authority is "available by phone" or will "review the decisions tomorrow." +**Fix:** Do not start the sprint. The Decider must be present for all key decisions, especially target selection. Reschedule if necessary. diff --git a/.agents/skills/design-sprint/references/recruiting.md b/.agents/skills/design-sprint/references/recruiting.md new file mode 100644 index 00000000..f0d6d50e --- /dev/null +++ b/.agents/skills/design-sprint/references/recruiting.md @@ -0,0 +1,315 @@ +# User Recruitment for Design Sprints + +Recruiting the right participants for Friday's interviews is one of the most important and most underestimated parts of the design sprint. Test with the wrong people and you get misleading feedback. Test with nobody and you wasted the week. Start recruiting at least two weeks before the sprint begins. + + +## Table of Contents +1. [Recruitment Timeline](#recruitment-timeline) +2. [Defining the Target Participant](#defining-the-target-participant) +3. [Screener Survey](#screener-survey) +4. [Where to Find Participants](#where-to-find-participants) +5. [Incentive Guidelines](#incentive-guidelines) +6. [Scheduling Logistics](#scheduling-logistics) +7. [No-Show Prevention](#no-show-prevention) +8. [Diverse Participant Selection](#diverse-participant-selection) +9. [Legal Considerations](#legal-considerations) +10. [Recruitment Checklist](#recruitment-checklist) + +--- + +## Recruitment Timeline + +| When | Action | Owner | +|------|--------|-------| +| Sprint minus 3 weeks | Define target participant profile with the team | Sprint Master + Decider | +| Sprint minus 2.5 weeks | Write screener survey | Sprint Master or Recruiter | +| Sprint minus 2 weeks | Post screener to recruitment channels | Recruiter | +| Sprint minus 10 days | Review screener responses, shortlist candidates | Recruiter | +| Sprint minus 8 days | Invite 8 candidates (6 primary + 2 backup) | Recruiter | +| Sprint minus 5 days | Confirm 6 participants, send calendar invitations | Recruiter | +| Sprint minus 2 days | Send reminder email with logistics (time, location, parking, contact) | Recruiter | +| Sprint minus 1 day | Send SMS reminder | Recruiter | +| Friday 8:00 AM | Send final "See you at [time]" text | Recruiter | + +### Why 6 Participants for 5 Slots + +Expect a 10-20% no-show rate even with the best recruitment process. Scheduling 6 ensures you hit 5 interviews. If all 6 show up, run the extra interview or pay the backup participant and thank them. + +## Defining the Target Participant + +### Start with the Sprint Target + +The participant profile should match the customer type identified on Monday. Ask: + +- Who is the target customer for the part of the journey we are testing? +- What demographics, behaviors, or roles define this person? +- What experience level should they have with the problem space? +- What experience level should they have with your product (if any)? + +### Participant Profile Template + +``` +TARGET PARTICIPANT PROFILE + +Role/Title: [e.g., Marketing manager at a company with 50-200 employees] +Experience: [e.g., Has used at least 2 project management tools in the past year] +Behavior: [e.g., Currently manages 3+ active projects simultaneously] +Excluded: [e.g., Not a current customer, not a competitor employee, not in the tech industry] +Nice to have: [e.g., Mix of genders, age 25-55, different company sizes] +``` + +### Common Participant Types + +| Sprint Focus | Ideal Participant | +|-------------|-------------------| +| Consumer app onboarding | People who match the target demographic and have never seen the product | +| B2B SaaS feature | Professionals in the target role who currently use a competitor | +| E-commerce redesign | People who have purchased similar products online in the past 90 days | +| Healthcare product | Patients with the target condition or caregivers who manage it | +| Internal tool | Employees in the target department who would use the tool daily | + +## Screener Survey + +### Purpose + +A screener survey filters applicants so you interview only people who match your target profile. It should take 2-3 minutes to complete and disqualify people who do not fit. + +### Screener Survey Template + +``` +SCREENER SURVEY: [Sprint Name] + +Thank you for your interest in participating in a product feedback session. +This survey takes about 2 minutes. + +1. What is your current job title? + [Open text] + +2. How many people work at your company? + ( ) 1-10 + ( ) 11-50 + ( ) 51-200 + ( ) 201-1000 + ( ) 1000+ + +3. Which of the following tools do you currently use? (Select all that apply) + [ ] Tool A + [ ] Tool B + [ ] Tool C + [ ] None of the above + +4. How often do you [target behavior]? + ( ) Daily + ( ) Weekly + ( ) Monthly + ( ) Rarely + ( ) Never + +5. Have you used [your product name] before? + ( ) Yes, currently use it + ( ) Yes, used it in the past + ( ) No, never used it + ( ) I have heard of it but never tried it + +6. On a scale of 1-5, how frustrated are you with your current solution for [problem]? + ( ) 1 - Not at all frustrated + ( ) 2 + ( ) 3 + ( ) 4 + ( ) 5 - Extremely frustrated + +7. Are you available on [Friday date] between [time range] for a 45-minute in-person/video session? + ( ) Yes + ( ) No + +8. What is the best email address to reach you? + [Open text] + +9. What is your phone number? (for scheduling confirmation only) + [Open text] +``` + +### Scoring the Screener + +Create a scoring rubric before reviewing responses: + +| Question | Ideal Answer | Points | +|----------|-------------|--------| +| Job title | Matches target role | 2 | +| Company size | Matches target segment | 1 | +| Tools used | Uses competitor (not your product) | 2 | +| Behavior frequency | Daily or weekly | 2 | +| Prior product experience | Never used or heard of it | 2 | +| Frustration level | 3 or higher | 1 | +| Availability | Yes | Required (disqualify if no) | + +**Threshold:** Invite participants who score 7+ out of 10. + +## Where to Find Participants + +### B2C Products + +| Channel | Pros | Cons | Cost | +|---------|------|------|------| +| Social media ads (Instagram, Facebook) | Fast, targetable | Lower quality, may attract "professional testers" | $50-200 in ad spend | +| Craigslist / local classifieds | Cheap, fast | Unpredictable quality | Free + incentive | +| Community groups (Reddit, Discord, Facebook Groups) | Engaged, relevant | May skew toward power users | Free + incentive | +| Intercept at physical locations (coffee shops, stores) | Real people in natural context | Time-consuming, limited volume | Free + incentive | +| Customer email list (non-current-users segment) | Pre-qualified interest | May bias toward people already favorable | Free + incentive | + +### B2B Products + +| Channel | Pros | Cons | Cost | +|---------|------|------|------| +| LinkedIn outreach | Highly targetable by role and company | Low response rate (5-10%) | Free + incentive | +| Industry events and meetups | Engaged professionals | Timing dependent | Free + incentive | +| Professional associations | Quality participants | Slow process | Varies | +| Recruitment platforms (see below) | Reliable, pre-screened panels | Expensive | $150-300 per participant | +| Partner introductions | Warm leads, high quality | Favors existing relationships | Free + incentive | +| Sales team referrals (non-customers) | Know the persona well | May introduce bias | Free + incentive | + +### Recruitment Platforms + +| Platform | Best For | Cost Per Participant | Turnaround | +|----------|----------|---------------------|------------| +| UserTesting | Quick unmoderated studies; also supports moderated | $30-100 (unmoderated), $150+ (moderated) | 1-3 days | +| Respondent.io | B2B and niche audiences | $100-300 (B2B), $50-100 (B2C) | 3-7 days | +| User Interviews | Broad consumer and B2B panels | $50-150 | 2-5 days | +| Ethnio | Intercept recruiting from your own website | $50-100 + subscription | 1-7 days | +| Prolific | Academic-quality panels, diverse demographics | $10-30 | 1-2 days | + +## Incentive Guidelines + +### How Much to Pay + +| Participant Type | Recommended Incentive | Format | +|-----------------|----------------------|--------| +| General consumer | $50-75 for 45 minutes | Gift card (Amazon, Visa) | +| Professional (B2B, mid-level) | $100-150 for 45 minutes | Gift card or direct payment | +| Senior executive (VP+) | $200-300 for 45 minutes | Donation to charity of choice or gift card | +| Medical professional | $200-400 for 45 minutes | Direct payment | +| Hard-to-reach niche | $150-300+ for 45 minutes | Whatever the market demands | + +### Incentive Principles + +- Pay enough to attract quality participants, not so much that people lie on the screener to qualify +- Pay immediately after the session (do not make them wait for a check in the mail) +- Digital gift cards are the easiest to distribute +- For B2B executives, offering a "donation to the charity of your choice" can be more effective than a personal payment +- Always pay no-shows if they gave 24-hour notice of cancellation (it maintains your reputation) + +## Scheduling Logistics + +### Time Slot Structure + +| Slot | Time | Purpose | +|------|------|---------| +| 1 | 9:45 - 10:30 | Interview 1 | +| Buffer | 10:30 - 11:00 | Team discussion, notes | +| 2 | 11:00 - 11:45 | Interview 2 | +| Buffer | 11:45 - 12:15 | Team discussion, notes | +| 3 | 12:15 - 1:00 | Interview 3 | +| Lunch | 1:00 - 1:45 | Break | +| 4 | 1:45 - 2:30 | Interview 4 | +| Buffer | 2:30 - 3:00 | Team discussion, notes | +| 5 | 3:00 - 3:45 | Interview 5 | +| 6 (backup) | 4:00 - 4:45 | Backup slot if a morning participant no-showed | + +### Confirmation Messages + +**Initial invitation email:** Thank the participant for completing the survey. Include the date, time, location (or video link), duration (45 minutes), incentive amount, and a request to confirm by reply. + +**Reminder (2 days before):** Restate date, time, location, duration, and incentive. Include your phone number. Ask them to let you know if they can no longer make it so you can offer their spot to someone else. + +## No-Show Prevention + +### Tactics That Reduce No-Shows + +| Tactic | Impact | +|--------|--------| +| Require confirmation reply (not just calendar accept) | High | +| Send 3 reminders (confirmation, 2-day, morning-of) | High | +| Include your personal phone number in communications | Medium | +| Offer to reschedule if they have a conflict | Medium | +| Over-recruit by 1-2 participants | High (mitigates no-shows) | +| Ask for their phone number and text the morning of | High | +| Make the incentive attractive enough | Medium | + +### What to Do When Someone No-Shows + +1. Wait 10 minutes past the scheduled time +2. Send a text: "Hi [Name], we are ready for you at [location]. Are you on your way?" +3. If no response after 5 more minutes, move on +4. Shift the schedule: pull the backup participant into the empty slot +5. If no backup is available, run 4 interviews instead of 5 (still produces patterns) + +## Diverse Participant Selection + +### Why Diversity Matters + +If all 5 participants are 30-year-old tech workers in San Francisco, you are testing with a narrow slice of your potential customer base. Diverse participants reveal a wider range of reactions, accessibility issues, and cultural considerations. + +### Diversity Dimensions to Consider + +- Age range (not all 25-35) +- Gender balance +- Technical proficiency (mix of tech-savvy and less technical) +- Geographic location (if testing remotely) +- Company size and industry (for B2B) +- Accessibility needs (include at least one participant who uses assistive technology, if relevant) + +### Practical Approach + +You only have 5 participants, so you cannot represent every dimension. Pick 2-3 diversity factors that are most relevant to your product and ensure variation across those factors. + +## Legal Considerations + +### Recording Consent + +Before recording any interview: + +1. Inform the participant that the session will be recorded (audio and video) +2. Explain how the recording will be used (internal review only) +3. Get verbal consent on camera: "Do I have your permission to record this session?" +4. If using a written consent form, have them sign before the interview begins + +### Key Legal Points + +- **Consent form:** Cover audio/video recording, internal-only use of recordings, right to stop the session at any time, and guaranteed incentive regardless of completion. Have participants sign before the interview begins. +- **NDAs:** Use a simple one-page NDA for pre-launch products. Do not require one for public products. If a participant refuses, pay them and do not show the prototype. +- **Data privacy:** Collect only what is needed, store securely, delete recordings within 30 days, and comply with GDPR/CCPA or relevant local regulations. + +## Recruitment Checklist + +### 3 Weeks Before Sprint + +- [ ] Target participant profile defined +- [ ] Screener survey written and tested +- [ ] Recruitment channels identified +- [ ] Budget approved for incentives and recruitment platform fees + +### 2 Weeks Before Sprint + +- [ ] Screener posted to recruitment channels +- [ ] Responses are being reviewed daily +- [ ] Shortlist of candidates created + +### 1 Week Before Sprint + +- [ ] 6 participants confirmed (5 primary + 1 backup) +- [ ] Calendar invitations sent with all logistics +- [ ] Consent forms prepared +- [ ] Incentives purchased (gift cards, etc.) + +### 2 Days Before Sprint + +- [ ] Reminder emails sent to all participants +- [ ] Backup participant confirmed + +### Friday Morning + +- [ ] Morning-of text messages sent +- [ ] Interview room set up +- [ ] Consent forms printed +- [ ] Incentives ready to distribute +- [ ] Backup plan in place for no-shows diff --git a/.agents/skills/design-sprint/references/remote-sprints.md b/.agents/skills/design-sprint/references/remote-sprints.md new file mode 100644 index 00000000..3c930f92 --- /dev/null +++ b/.agents/skills/design-sprint/references/remote-sprints.md @@ -0,0 +1,316 @@ +# Remote Design Sprints + +Running a design sprint with a distributed team requires deliberate adaptation of every exercise. The core principles remain the same: time-box, work individually, let the Decider decide, prototype, and test. But the tools, energy management, and communication patterns must change to account for screen fatigue, time zones, and the absence of a shared physical space. + + +## Table of Contents +1. [Tool Stack](#tool-stack) +2. [Time Zone Considerations](#time-zone-considerations) +3. [Adapting Each Day for Remote](#adapting-each-day-for-remote) +4. [Compressed Schedule Options](#compressed-schedule-options) +5. [Remote-Specific Exercise Adaptations](#remote-specific-exercise-adaptations) +6. [Energy Management for Remote Participants](#energy-management-for-remote-participants) +7. [Async vs Sync Quick Reference](#async-vs-sync-quick-reference) +8. [Remote Prototype Testing Tools](#remote-prototype-testing-tools) +9. [Common Remote Sprint Failures and Fixes](#common-remote-sprint-failures-and-fixes) +10. [Remote Sprint Checklist](#remote-sprint-checklist) + +--- + +## Tool Stack + +### Essential Tools + +| Purpose | Recommended Tool | Why | +|---------|-----------------|-----| +| Digital whiteboard | Miro or FigJam | Replaces physical whiteboards for mapping, HMWs, voting | +| Video conferencing | Zoom or Google Meet | Screen sharing, breakout rooms, recording | +| Prototyping | Figma | Real-time collaboration, easy sharing for testing | +| Async video | Loom | Lightning Demos, expert interviews that can be watched asynchronously | +| Chat | Slack or Teams | Side channel for logistics, questions, and sharing links | +| Timer | Cuckoo.team or Toggl Timer | Shared visible timer that all participants see | +| File sharing | Google Drive or Notion | Central place for templates, assets, and outputs | + +### Miro/FigJam Board Setup + +Create a single board for the entire sprint with clearly labeled sections: + +``` ++-------------------+-------------------+-------------------+ +| MONDAY | TUESDAY | WEDNESDAY | +| - Long-term goal | - Lightning Demos | - Art Museum | +| - Sprint questions| - Sketch uploads | - Heat map | +| - Customer map | | - Straw poll | +| - HMW notes | | - Storyboard | +| - Target | | | ++-------------------+-------------------+-------------------+ +| THURSDAY | FRIDAY | PARKING LOT | +| - Prototype link | - Note-taking | - Unresolved | +| - Interview script| grid | questions | +| - Trial run notes | - Patterns | - Future ideas | +| | - Next steps | | ++-------------------+-------------------+-------------------+ +``` + +Pre-populate each section with templates, instructions, and placeholder sticky notes before the sprint begins. + +## Time Zone Considerations + +### Single Time Zone (All Participants Within 2 Hours) + +Run the sprint at normal hours for the majority. Adjust start/end times by 30-60 minutes to accommodate the edges. + +### Two Time Zones (3-6 Hours Apart) + +| Approach | Schedule | +|----------|----------| +| Overlap window | Find the 4-5 hour window where both zones are in working hours. Run all synchronous exercises during this window | +| Extended async | Use 2-3 hours of sync time per day and shift more exercises to async | + +**Example: New York (EST) + London (GMT), 5-hour difference:** + +| Time (EST) | Time (GMT) | Activity | +|------------|------------|----------| +| 8:00 AM | 1:00 PM | Sync block begins | +| 8:00 - 8:30 | 1:00 - 1:30 | Recap and framing | +| 8:30 - 11:30 | 1:30 - 4:30 | Core exercises (sync) | +| 11:30 - 12:00 | 4:30 - 5:00 | Wrap-up and async assignments | +| 12:00 - 2:00 | 5:00+ (done) | US team does async work | + +### Three or More Time Zones (7+ Hours Apart) + +A fully synchronous 5-day sprint is impractical. Use compressed schedules (see below), heavy async with short sync check-ins, or extend the sprint across 7-8 calendar days. + +## Adapting Each Day for Remote + +### Remote Monday: Map + +**Sync exercises:** +- Long-term goal (30 min, video call, everyone writes in Miro simultaneously) +- Sprint questions (30 min, same format) +- Customer journey map (45 min, Sprint Master draws in Miro while team directs) + +**Async exercises:** +- Expert interviews can be pre-recorded on Loom (10-15 min each, team watches on their own time) +- HMW notes: each person adds sticky notes to the Miro board asynchronously after watching expert videos + +**Sync decision:** +- HMW voting (15 min, use Miro's built-in voting feature) +- Target selection with Decider (15 min, video call) + +### Remote Tuesday: Sketch + +**Sync exercises:** +- Lightning Demos (45 min, each person shares screen for 3 minutes) + +**Async exercises:** +- Notes phase (20 min, everyone reviews the Miro board on their own) +- Ideas phase (20 min, individual work) +- Crazy 8s (8 min, individual work, upload photos of paper sketches) +- Solution Sketch (60-90 min, individual work) + +**How to handle sketches remotely:** +1. Sketch on paper with a thick marker (same as in-person) +2. Photograph each panel with a phone +3. Upload to the designated Miro area by a set deadline +4. Each sketch gets its own frame in Miro, numbered and anonymous + +Set a firm deadline for sketch uploads. The Sprint Master confirms receipt of all sketches. No one views others' sketches until Wednesday. + +### Remote Wednesday: Decide + +**Sync exercises (these must be synchronous):** +- Art Museum: everyone silently reviews sketches in Miro, placing dot stickers (20 min) +- Speed Critique: Sprint Master shares screen and narrates each sketch (3 min per sketch) +- Straw Poll: everyone places their vote simultaneously in Miro (5 min) +- Supervote: Decider places their votes (5 min) + +**Async/sync exercises:** +- Storyboard: can be done with the Sprint Master building in Miro while the team provides direction on a video call, or the Sprint Master can draft it async and get sync approval + +**Remote Wednesday tips:** +- The Art Museum works surprisingly well in Miro: participants browse and place dots silently +- During Speed Critique, the Sprint Master must share screen and control the zoom/navigation +- Use a different color dot for each participant to track who voted for what +- The Decider should be present for the entire sync session + +### Remote Thursday: Prototype + +**Sync exercises:** +- Morning kick-off: assign roles and divide storyboard (30 min) +- Mid-day check-in (15 min) +- End-of-day review: walk through prototype together (30 min) +- Trial run (30 min) + +**Async work:** +- Building the prototype (individual or paired work in Figma) +- Writing copy (Writer works independently, shares in Slack) +- Gathering assets (Collector works independently) +- Writing the interview script (Interviewer works independently) + +**Remote Thursday tips:** +- Figma's real-time collaboration makes remote prototyping nearly as efficient as in-person +- The Stitcher should set up the Figma file structure before the morning kick-off +- Use a shared Slack channel for quick questions and asset sharing +- The Sprint Master should check in every 90 minutes via a quick standup message + +### Remote Friday: Test + +**Interview options:** +- Video call interview (Zoom, Google Meet) with the participant sharing their screen +- Unmoderated testing platform (UserTesting.com, Maze) for asynchronous feedback +- Moderated video call is strongly preferred for design sprints + +**Observation setup:** +- All observers join a separate "observation" Zoom call +- The Interviewer conducts the interview on the main call +- Screen share from the Interviewer's call is piped to the observation call +- Observers take notes in the shared Miro grid (same format as in-person) +- Use a shared chat channel for observers to flag interesting moments in real time + +**Remote Friday tips:** +- Test the video/audio setup 24 hours before the first interview +- Send participants a test link to verify their screen sharing works +- Have a backup plan if a participant cannot share their screen (the Interviewer controls the prototype and asks the participant to direct them) +- Between interviews, do a quick 5-minute debrief on the observation call + +## Compressed Schedule Options + +### 4-Day Sprint + +Combine Monday and Tuesday into a single day by compressing exercises and using async pre-work. + +| Day | Activities | +|-----|-----------| +| Pre-work (async) | Expert interviews via Loom, Lightning Demos recorded and shared | +| Day 1 (Mon) | Long-term goal, sprint questions, map, HMW, target + Notes, Ideas, Crazy 8s, Solution Sketch | +| Day 2 (Tue) | Art Museum, Speed Critique, Voting, Storyboard | +| Day 3 (Wed) | Prototype | +| Day 4 (Thu) | Test and debrief | + +**4-day sprint trade-offs:** +- Day 1 is very long and intense (8-9 hours of focused work) +- Less time for expert interviews (use async pre-recorded format) +- Solution sketches have less incubation time +- Works best for experienced sprint teams + +### 3-Day Sprint + +Requires significant async pre-work (expert interviews, Lightning Demos, goal/questions drafts done 1 week before). Day 1 covers finalize/map/sketch/decide. Day 2 is prototyping. Day 3 is testing and debrief. Works for focused problems where the team has deep context. Not recommended for first-time sprints. + +## Remote-Specific Exercise Adaptations + +### Dot Voting in Miro + +1. Create a "voting" frame in the Miro board +2. Give each participant a set number of colored dots (use Miro's sticker feature or small circles) +3. Set a timer (visible to all via the shared timer) +4. Lock the board after voting to prevent late changes +5. Use Miro's "hide cursors" feature during voting to prevent following behavior + +### Crazy 8s: Remote Version + +Sketch on paper with a thick marker (same as in-person), photograph each panel, and upload to the designated Miro area. The Sprint Master counts down each minute on the video call. Paper and photograph is strongly preferred over digital sketching in Miro because the physical act of folding and drawing creates energy that digital tools cannot replicate. + +### Storyboard: Remote Version + +The Sprint Master builds the storyboard in Miro while the team provides direction over video call. The Sprint Master shares their screen, draws each frame based on team input, and controls the final layout. Alternatively, assign one person to draft the storyboard async and review sync the next morning. + +## Energy Management for Remote Participants + +### Screen Fatigue Is Real + +Remote sprints are more exhausting than in-person sprints because video calls require more cognitive effort than face-to-face conversation. Plan for it. + +### Remote Energy Tactics + +| Tactic | Implementation | +|--------|---------------| +| Camera breaks | Turn cameras off during individual work, on during group work | +| Shorter sync blocks | Max 90 minutes of sync time before a break | +| Physical movement | 5-minute stretch break every 60 minutes | +| Async work blocks | Alternate between sync discussion and async individual work | +| Music during silent work | Sprint Master plays music via screen share or shares a playlist link | +| Chat engagement | Use emoji reactions in chat to maintain energy without interrupting | + +### Daily Structure for Remote Energy + +``` +Sync block 1 (90 min) → Break (15 min) → Async work (60 min) → +Sync block 2 (60 min) → Lunch (60 min) → Async work (90 min) → +Sync block 3 (60 min) → Break (15 min) → Wrap-up sync (15 min) +``` + +This structure limits total sync time to approximately 3.5 hours per day while maintaining 6-7 hours of productive sprint work. + +## Async vs Sync Quick Reference + +**Must be sync:** Long-term goal discussion, customer journey map, all voting (HMW, Art Museum, straw poll, supervote), speed critique, user interviews, debrief. + +**Can be async:** Expert interviews (Loom), HMW note writing, four-step sketch, prototype building, asset gathering, copy writing. + +**Either way:** Lightning Demos (sync is more energetic, async Loom works for time zone conflicts), storyboard (Sprint Master can draft async, team reviews sync). + +## Remote Prototype Testing Tools + +**Moderated (recommended):** Zoom + Figma prototype link (participant shares screen), Lookback, or UserZoom. + +**Unmoderated (backup):** Maze, UserTesting, or Useberry. Use when you cannot schedule 5 participants on the same day or time zones make live interviews impossible. Trade-off: no follow-up questions, less natural think-aloud, and you miss body language. + +## Common Remote Sprint Failures and Fixes + +### Multitasking During Sync Sessions + +**Problem:** Participants check email, Slack, or work on other tasks during video calls. +**Fix:** Set a ground rule on Day 1: close all other tabs and apps during sync time. Use frequent engagement tactics: polls, voting, round-robin sharing. Keep sync blocks under 90 minutes. The Sprint Master calls on people by name regularly. + +### Poor Audio/Video Quality + +**Problem:** Participants join from noisy environments or with bad connections, disrupting the flow. +**Fix:** Require headphones with a microphone. Test audio/video setup the day before the sprint. Have a backup plan: phone dial-in for audio if video fails. Encourage wired internet connections over WiFi for stability. + +### Miro Board Chaos + +**Problem:** The Miro board becomes a mess of overlapping sticky notes, orphaned elements, and unclear structure. +**Fix:** The Sprint Master sets up the board with clear sections, labels, and locked background elements before the sprint. Only the Sprint Master should move structural elements. Use frames to contain each exercise. Lock completed sections so they are not accidentally edited. + +### Lost Momentum Between Days + +**Problem:** In a physical sprint, the room and the walls full of work maintain continuity. Remotely, people close their laptop and lose context overnight. +**Fix:** Start each day with a 10-minute recap. The Sprint Master walks through the Miro board, highlighting where the team left off and what happens today. Send a short end-of-day summary via Slack or email with a screenshot of the day's output. + +### Sketches Are Hard to Read When Photographed + +**Problem:** Participants upload blurry or poorly lit photos of their paper sketches, making the Art Museum difficult. +**Fix:** Require thick black markers (thin pens do not photograph well). Provide instructions for photographing: lay the paper flat, use good lighting, crop to the sketch only. Alternatively, allow digital sketching in Miro for participants who prefer it. + +### The Decider Is Not Fully Engaged + +**Problem:** The Decider joins for 10 minutes and then drops off, leaving key decisions hanging. +**Fix:** Before the sprint, get the Decider's explicit commitment to attend all voting and decision sessions. Create a "Decider schedule" showing the specific times they are needed (typically 30-60 minutes per day, not the full day). If the Decider cannot commit, postpone the sprint. + +### Time Zone Conflicts Kill Participation + +**Problem:** Team members in distant time zones attend at inconvenient hours and contribute less. +**Fix:** Identify the minimum overlap window and schedule all critical sync activities there. Shift the burden of inconvenience across the week. Use async exercises to maximize contribution from all time zones. + +### Friday Testing Feels Disconnected + +**Problem:** The team watches user interviews on video but does not feel the energy and immediacy of in-person observation. +**Fix:** Use a dedicated observation channel where team members react and note observations in real time. Between each interview, do a live 5-minute debrief on video. + +## Remote Sprint Checklist + +- [ ] Tool accounts set up for all participants (Miro, Zoom, Figma) +- [ ] Miro board pre-populated with templates and structure +- [ ] Sprint schedule adjusted for time zones +- [ ] Async vs sync plan communicated to all participants +- [ ] Tech check completed (audio, video, screen sharing) +- [ ] Supplies shipped to remote participants (thick markers, blank paper, sticky notes) +- [ ] Each day starts with a 10-minute recap and board walkthrough +- [ ] Sync blocks limited to 90 minutes before a break +- [ ] All outputs captured in the Miro board +- [ ] End-of-day summary sent to all participants +- [ ] Friday participants confirmed and tested for screen sharing +- [ ] Observation channel set up (separate from interview call) +- [ ] Note-taking grid created in Miro diff --git a/.agents/skills/design-sprint/references/thursday.md b/.agents/skills/design-sprint/references/thursday.md new file mode 100644 index 00000000..14642fe8 --- /dev/null +++ b/.agents/skills/design-sprint/references/thursday.md @@ -0,0 +1,292 @@ +# Thursday: Build the Prototype + +Thursday is about execution. The team transforms Wednesday's storyboard into a realistic prototype that customers can react to on Friday. The mantra for the day: fake it. You are not building a product. You are building a facade that looks real enough to provoke honest reactions. + +## Schedule Overview + +| Time | Activity | Duration | +|------|----------|----------| +| 10:00 - 10:30 | Assign roles and divide storyboard | 30 min | +| 10:30 - 1:00 | Build: Makers create, Writer writes, Collector gathers | 150 min | +| 1:00 - 1:30 | Lunch (staggered if needed) | 30 min | +| 1:30 - 3:00 | Stitch: Assemble all pieces into a single prototype | 90 min | +| 3:00 - 3:30 | Review: Walk through the full prototype as a team | 30 min | +| 3:30 - 4:00 | Fix: Address gaps and polish rough spots | 30 min | +| 4:00 - 4:30 | Trial run with someone outside the team | 30 min | +| 4:30 - 5:00 | Interview script review and Friday prep | 30 min | + +## The Prototype Mindset + +### Fake It + +The prototype does not need to work. It needs to look like it works. Users will click through screens, see realistic content, and form opinions based on appearance, not functionality. + +| Real Product | Sprint Prototype | +|-------------|-----------------| +| Database stores user data | Fake data hard-coded into screens | +| Algorithm generates recommendations | Hand-picked recommendations placed in the design | +| Payment processing | A screen that says "Payment successful" | +| Search functionality | Pre-built results page for one specific query | +| User authentication | Skip login or show a "Welcome, Sarah" screen | + +### Why Faking Works + +Users do not evaluate the code behind a screen. They evaluate: +- Does this make sense? +- Do I trust this? +- Can I figure out what to do? +- Does this solve my problem? + +A well-crafted facade answers all of these questions just as effectively as a working product. + +## Goldilocks Quality + +The prototype must sit in a narrow quality band. Too rough, and customers cannot react realistically. Too polished, and you waste precious time on details that do not affect the test. + +### Quality Spectrum + +| Too Low (Avoid) | Just Right (Target) | Too High (Avoid) | +|-----------------|--------------------|--------------------| +| Wireframes with gray boxes | Realistic screens with real content | Pixel-perfect design with animations | +| Handwritten labels | Typed text in a clean font | Custom typography and brand guidelines | +| Placeholder images | Stock photos or screenshots | Professional photography or illustrations | +| No color | Basic color palette | Full brand color system | +| Paper prototype | Digital click-through | Working code with real backend | +| "Lorem ipsum" text | Real headlines and descriptions | Copywriter-polished marketing copy | + +### The Test: Show a screen to someone outside the team for 5 seconds + +- If they say "Is this a wireframe?" — too low +- If they say "When did you build this?" — too high (or just right) +- If they say "Oh, interesting, what is this?" — just right + +## Role Assignments + +### Makers (2-3 people) + +**Responsibility:** Build the individual screens or components of the prototype. + +**Best suited for:** Designers, front-end developers, or anyone comfortable with visual tools. + +**What they do:** +- Take assigned storyboard frames +- Create realistic-looking screens +- Follow the storyboard exactly (no improvising) +- Use real content, not placeholders + +### Stitcher (1 person) + +**Responsibility:** Assemble all screens into a single, navigable prototype. + +**Best suited for:** The most experienced designer or someone who knows the prototyping tool well. + +**What they do:** +- Combine screens from Makers into one prototype +- Add transitions and hotspots (clickable areas) +- Ensure the flow matches the storyboard sequence +- Test every click path before the team review + +### Writer (1 person) + +**Responsibility:** Write all text that appears in the prototype. + +**Best suited for:** Marketer, product manager, or anyone with strong writing skills. + +**What they do:** +- Write headlines, subheadlines, body copy +- Write button labels, form field labels, navigation items +- Write error messages and confirmation messages +- Keep copy concise and realistic + +**Writer's checklist:** +- [ ] Every screen has a clear headline +- [ ] Button labels describe the action ("Start free trial" not "Submit") +- [ ] No placeholder text remains +- [ ] Copy matches the tone of a real product (not overly formal or casual) +- [ ] Key value propositions are clear + +### Collector (1-2 people) + +**Responsibility:** Gather all visual assets needed by the Makers. + +**What they do:** +- Find stock photos (Unsplash, Pexels) +- Collect icons (Noun Project, Feather Icons) +- Screenshot competitor interfaces for reference +- Source logos, avatars, and sample data +- Organize assets in a shared folder + +### Interviewer (1 person) + +**Responsibility:** Prepare for Friday's user interviews. + +**What they do (while others build):** +- Write the interview script (see Friday reference) +- Prepare context questions +- Plan tasks for users to complete with the prototype +- Practice the interview with a colleague +- Set up the interview room + +## Prototyping Tools by Product Type + +### Web and Mobile Apps + +| Tool | Best For | Learning Curve | Fidelity | +|------|----------|---------------|----------| +| Figma | Most common choice. Teams often already use it | Medium | High | +| Keynote / PowerPoint | Quick click-through with linked slides | Low | Medium | +| InVision | Uploading static screens with hotspots | Low | Medium | +| Framer | Interactive prototypes with real components | High | Very high | + +### Physical Products + +| Approach | When to Use | +|----------|------------| +| Video walkthrough | Show someone using a mockup or 3D print | +| Modified existing product | Tape labels, add stickers, rearrange components | +| 3D-printed shell | When form factor matters for the test | +| Wizard of Oz | Human behind the curtain simulating the product's behavior | + +### Services and Experiences + +| Approach | When to Use | +|----------|------------| +| Role-play video | Film a scripted interaction with actors | +| Brochure or one-pager | Test the value proposition before building | +| Fake landing page | Test whether people click "Sign up" | +| Concierge prototype | Deliver the service manually to see if customers value it | + +### AI and Data Products + +| Approach | When to Use | +|----------|------------| +| Pre-scripted responses | Show what the AI "would" say for specific queries | +| Curated results page | Hand-pick the "algorithm's" recommendations | +| Before/after comparison | Show input and output without the actual processing | + +## Step-by-Step Prototype Building + +### Step 1: Divide the Storyboard (10:00 - 10:30) + +1. Display Wednesday's storyboard (photo or whiteboard) +2. Number each frame +3. Assign frames to Makers: "You take frames 1-4, you take frames 5-8, you take frames 9-12" +4. Confirm the Stitcher knows the assembly plan +5. Writer begins drafting copy for all frames simultaneously +6. Collector starts gathering assets immediately + +### Step 2: Build in Parallel (10:30 - 1:00) + +**Makers:** +- Build screens for assigned frames +- Follow the storyboard exactly +- Use the Writer's copy as it becomes available +- Use the Collector's assets +- Ask the Stitcher about sizing, layout conventions, and shared elements + +**Stitcher:** +- Set up the master file (Figma project, Keynote deck) +- Define shared elements: header, footer, navigation, button styles +- Begin assembling screens as Makers finish them +- Build the clickable flow + +**Coordination check-ins:** Every 45 minutes, the Sprint Master does a quick standing check-in: "What is done? What is blocked? What do you need?" + +### Step 3: Stitch Together (1:30 - 3:00) + +1. Stitcher assembles all screens into the final prototype +2. Add clickable hotspots and transitions +3. Ensure the flow follows the storyboard sequence exactly +4. Fill any gaps (missing screens, broken links) + +### Step 4: Team Review (3:00 - 3:30) + +1. The entire team sits together +2. The Stitcher walks through the prototype, click by click +3. Compare each screen to the storyboard frame +4. Note issues on sticky notes: missing content, broken links, confusing flow +5. Prioritize fixes: critical (blocks the test) vs. nice-to-have + +### Step 5: Fix and Polish (3:30 - 4:00) + +- Fix critical issues only +- Do not add new features or screens +- Do not perfect the visual design +- Focus on: can a user complete the tasks we will assign on Friday? + +### Step 6: Trial Run (4:00 - 4:30) + +1. Find someone not on the sprint team (a colleague from another department) +2. The Interviewer conducts a practice interview using the prototype +3. The team watches and notes: + - Where does the trial user get confused? + - Are there broken links or dead ends? + - Does the prototype flow match what we want to test? +4. Fix any issues the trial run reveals + +## Interview Script Writing Guide + +While the team builds, the Interviewer writes the script for Friday. The script should cover: + +### Script Structure + +| Section | Duration | Content | +|---------|----------|---------| +| Welcome | 2 min | Introduction, consent for recording, think-aloud instructions | +| Background | 5 min | Questions about the participant's current behavior and context | +| First impression | 3 min | Show the first screen, ask "What is this? What would you do?" | +| Task completion | 15 min | 2-3 specific tasks to complete using the prototype | +| Debrief | 5 min | Overall impressions, who is this for, what worked, what confused | + +### Task Writing Tips + +Good tasks are: +- Open-ended: "Find a project management tool that fits your team" (not "Click the blue button") +- Scenario-based: "Imagine you just got an email from a colleague recommending this tool" +- Specific enough to test the sprint questions: "You have a team of 5 and a budget of $100/month" + +## Thursday Checklist + +- [ ] Roles assigned: Makers, Stitcher, Writer, Collector, Interviewer +- [ ] Storyboard frames divided among Makers +- [ ] All copy written by the Writer +- [ ] All assets gathered by the Collector +- [ ] Screens assembled into a clickable prototype by the Stitcher +- [ ] Full team review completed +- [ ] Critical issues fixed +- [ ] Trial run completed with someone outside the team +- [ ] Interview script written and reviewed +- [ ] Interview room set up (laptop, chairs, recording) +- [ ] Participants confirmed for Friday (check with recruiter) + +## Common Thursday Mistakes + +### Prototyping Features Not in the Storyboard + +**Problem:** A Maker adds a clever feature that was not in the storyboard because "users might ask about it." +**Fix:** Build only what is in the storyboard. Anything else wastes time and muddies the test. If the feature is missing and a user asks, that is useful data. + +### Over-Polishing Visual Design + +**Problem:** The team spends 2 hours choosing the right shade of blue. +**Fix:** Pick a simple, clean style and move on. Users react to the concept and flow, not the color palette. Use a pre-made UI kit or template to skip design decisions. + +### The Stitcher Becomes the Bottleneck + +**Problem:** Makers finish screens but the Stitcher cannot assemble fast enough. +**Fix:** The Stitcher should set up the master file and shared elements first thing. Makers should build in the shared format so assembly is drag-and-drop. + +### No Trial Run + +**Problem:** The team skips the trial run because they ran out of time. +**Fix:** The trial run is not optional. Cut polish time instead. A broken prototype on Friday wastes the entire week. Even a 15-minute trial run catches critical issues. + +### The Writer Writes Perfect Copy + +**Problem:** The Writer agonizes over every word, slowing the entire team. +**Fix:** Thursday copy is "good enough" copy. It needs to be clear and realistic, not award-winning. If the concept works, you will write better copy later. + +### Ignoring the Interview Script + +**Problem:** The Interviewer writes a script at 4:55 PM or wings it on Friday. +**Fix:** The Interviewer should spend the full day on script preparation and practice. A bad interview wastes a participant. The Interviewer should do at least one full practice run by 4:00 PM. diff --git a/.agents/skills/design-sprint/references/tuesday.md b/.agents/skills/design-sprint/references/tuesday.md new file mode 100644 index 00000000..f5ef5ce9 --- /dev/null +++ b/.agents/skills/design-sprint/references/tuesday.md @@ -0,0 +1,293 @@ +# Tuesday: Sketch Solutions + +Tuesday is about generating solutions, not discussing them. The day shifts from group understanding (Monday) to individual creation. By the end of Tuesday, every team member will have produced a detailed, self-explanatory solution sketch. The critical rule: work alone, think deeply, and let the ideas compete on Wednesday. + +## Schedule Overview + +| Time | Exercise | Duration | +|------|----------|----------| +| 10:00 - 10:15 | Recap Monday target | 15 min | +| 10:15 - 11:30 | Lightning Demos | 75 min | +| 11:30 - 12:00 | Divide or Swarm decision | 30 min | +| 12:00 - 1:00 | Lunch | 60 min | +| 1:00 - 1:20 | Notes (Step 1) | 20 min | +| 1:20 - 1:40 | Ideas (Step 2) | 20 min | +| 1:40 - 1:50 | Crazy 8s (Step 3) | 10 min | +| 1:50 - 3:20 | Solution Sketch (Step 4) | 90 min | +| 3:20 - 3:30 | Collect and seal sketches | 10 min | + +## Lightning Demos + +### Purpose + +Borrow ideas from existing products, competitors, and unrelated industries. Lightning Demos fill the creative tank before sketching begins. + +### Preparation (Before Tuesday) + +At the end of Monday, ask each team member to: + +- Find 2-3 products or features that solve a similar problem (even from different industries) +- Bookmark them or take screenshots +- Prepare a 3-minute walkthrough + +### How to Run Lightning Demos + +1. Each person gets 3 minutes to demo what they found +2. Show the product on screen or walk through screenshots +3. Explain: "Here is what they do, and here is what I think is interesting about it" +4. The Sprint Master captures the big idea on the whiteboard with a quick sketch and label +5. No debate or critique during demos. Just capture + +### What to Look For + +| Source | What to Capture | +|--------|----------------| +| Direct competitors | Features they got right, messaging that resonates | +| Adjacent industries | Interaction patterns that solve a similar problem differently | +| Non-tech examples | Retail, hospitality, or service experiences that feel effortless | +| Internal products | Other features in your own product that work well | +| Academic/research | Frameworks or data that could inspire a novel approach | + +### Example Lightning Demos + +**Sprint target:** Improve onboarding for a project management tool. + +- **Demo 1 (Trello):** "They show a sample board pre-filled with tasks so you immediately see how it works. The big idea: show, don't tell." +- **Demo 2 (Duolingo):** "They get you doing a lesson within 30 seconds, before even creating an account. The big idea: delay signup, lead with value." +- **Demo 3 (IKEA store layout):** "They force a path through the showroom so you see everything in context. The big idea: guided tour instead of open exploration." + +### Capture Format + +On the whiteboard, create a grid: + +``` +[Quick sketch] [Quick sketch] [Quick sketch] +"Show, don't "Delay signup, "Guided tour + tell" - Trello lead with value" path" - IKEA + - Duolingo +``` + +Each entry has a simple sketch and a 3-5 word label. By the end of Lightning Demos, you should have 10-20 captured ideas on the whiteboard. + +## Divide or Swarm + +### When to Divide + +If the target area on Monday's map has clearly separable components, assign different people to different sections. + +**Example:** If the target is "signup through first project," one group could tackle signup, another could tackle the first project experience. + +### When to Swarm + +If the target is a single, focused problem, everyone works on the same challenge independently. + +**Most sprints use Swarm.** When in doubt, swarm. Having 5-7 different approaches to the same problem produces richer options. + +## The Four-Step Sketch + +This is the core of Tuesday. Four progressively focused exercises move each person from reviewing existing ideas to creating a detailed solution. All four steps are done individually and in silence. + +### Step 1: Notes (20 minutes) + +**What to do:** + +1. Walk around the room silently +2. Review the whiteboard: long-term goal, sprint questions, customer journey map, HMW clusters, Lightning Demo captures +3. Take notes on paper about anything that catches your attention +4. Copy interesting ideas, jot down thoughts, highlight constraints + +**Tips:** + +- Use pen and paper, not a laptop +- Do not organize your notes; just capture raw material +- Pay special attention to the target area on the map +- Review the sprint questions: your sketch should try to answer at least one + +### Step 2: Ideas (20 minutes) + +**What to do:** + +1. Start doodling rough ideas on paper +2. Stick figures, flow diagrams, wireframes, word clouds: anything goes +3. Generate as many ideas as possible +4. Do not self-edit: ugly and half-baked is fine +5. Explore different directions, not just one + +**Tips:** + +- Set a personal goal of at least 8 distinct ideas +- Mix practical ideas with wild ones +- Think about the problem from the customer's perspective +- Consider ideas from Lightning Demos: how might you adapt them? + +### Step 3: Crazy 8s (8 minutes) + +**What to do:** + +1. Take a blank sheet of paper +2. Fold it in half three times to create 8 panels +3. Set a timer for 8 minutes +4. In each panel, sketch one variation of your best idea (1 minute per panel) +5. When the timer rings, stop immediately + +**Detailed Instructions:** + +| Panel | Time | Focus | +|-------|------|-------| +| 1 | 0:00 - 1:00 | Your best idea, simplest version | +| 2 | 1:00 - 2:00 | Same idea, different layout or flow | +| 3 | 2:00 - 3:00 | What if the user starts at a different point? | +| 4 | 3:00 - 4:00 | What if there were fewer steps? | +| 5 | 4:00 - 5:00 | What if it were more visual, less text? | +| 6 | 5:00 - 6:00 | What would the competitor version look like? | +| 7 | 6:00 - 7:00 | What is the most radical version? | +| 8 | 7:00 - 8:00 | Combine the best elements from panels 1-7 | + +**Why Crazy 8s Matter:** + +- Forces you past your first idea (which is rarely the best) +- Creates variations that lead to unexpected combinations +- The time pressure shuts down perfectionism +- Panel 8 often produces the breakthrough + +**Common Crazy 8s Mistakes:** + +- Drawing the same idea 8 times with trivial changes (push for real variation) +- Spending 4 minutes on panel 1 and rushing the rest (use a timer that beeps every minute) +- Giving up because you "can't draw" (stick figures and words are enough) + +### Step 4: Solution Sketch (60-90 minutes) + +**What to do:** + +1. Take 3 sheets of blank paper (or a large sheet divided into 3 panels) +2. Create a 3-panel storyboard showing a customer's experience with your solution +3. Panel 1: What triggers the customer to encounter your solution? +4. Panel 2: How does the customer interact with the core of your solution? +5. Panel 3: What is the result? What does success look like? + +**Solution Sketch Requirements:** + +- [ ] Self-explanatory: someone who was not in the room should understand it +- [ ] Has a catchy title at the top +- [ ] Anonymous: no name on the sketch +- [ ] Detailed enough to build: include button labels, headlines, key copy +- [ ] Shows the flow: arrows or numbered steps indicating sequence +- [ ] Fits the target from Monday + +### 3-Panel Storyboard Structure + +**Panel 1: Entry Point** + +What the customer sees first. Could be: +- A search result +- An email +- A notification +- A landing page +- A colleague's recommendation + +Draw the screen, message, or moment. Include real text, not "lorem ipsum." + +**Panel 2: Core Interaction** + +The heart of your solution. Show: +- What the interface looks like +- What the customer does (clicks, types, drags) +- What information they see +- How they progress through the experience + +This panel often needs the most detail. Use annotations and callouts. + +**Panel 3: Outcome** + +The result of using your solution: +- What does the customer see when they succeed? +- How do they feel? What confirmation do they get? +- What happens next? + +### Example Solution Sketch: Onboarding for a Project Management Tool + +- **Panel 1 "Welcome Screen":** Greeting by name, question about use case (Marketing / Engineering / Design), "Get started" button. Sets context. +- **Panel 2 "Guided Setup":** Name your first project field, invite team members field, note that starter tasks are auto-generated based on use case selection. Shows the core interaction. +- **Panel 3 "Your First Win":** Project board with pre-filled tasks, one already marked done, confetti animation, "Share with your team" call to action. Shows the successful outcome. + +## Tips for Non-Designers + +### You Do Not Need to Draw Well + +Solution sketches are about ideas, not artistry. Use: + +- **Rectangles** for screens and containers +- **Lines** for text (squiggly lines = body text) +- **Circles and arrows** for buttons and navigation +- **Stick figures** for people +- **Words** for headlines, labels, and key copy + +### Focus on These Elements + +1. **Headlines:** What does the customer read first? +2. **Key actions:** What button do they click? What do they type? +3. **Information hierarchy:** What is biggest/most prominent? +4. **Flow:** Where does the customer go from each step? +5. **Copy:** Write real words, not placeholder text + +### If You Are Stuck + +- Return to the Lightning Demo wall and adapt an idea +- Solve for one specific sprint question +- Draw your favorite competitor's approach, then change three things +- Think about the worst possible version, then invert it +- Start from the outcome (Panel 3) and work backwards + +## Collecting Sketches + +At the end of Tuesday: + +1. Everyone places their solution sketch face-down on the table +2. The Sprint Master collects them without looking +3. Sketches stay sealed until Wednesday morning +4. No peeking, no sharing, no discussing solutions over dinner + +This builds suspense and prevents bias. On Wednesday, every sketch gets a fair hearing. + +## Tuesday Checklist + +- [ ] Lightning Demos completed (10-20 ideas captured on whiteboard) +- [ ] Divide or Swarm decision made +- [ ] All four sketch steps completed by every team member +- [ ] Each person produced a 3-panel solution sketch +- [ ] Sketches are self-explanatory, titled, and anonymous +- [ ] Sketches collected and sealed +- [ ] No one has discussed or revealed their solution + +## Common Tuesday Mistakes + +### Lightning Demos Go Too Long + +**Problem:** Each demo takes 10 minutes instead of 3, eating into sketch time. +**Fix:** Use a visible timer. At 3 minutes, the Sprint Master says "Thank you, next." Capture the big idea and move on. + +### Group Discussion During Sketch Time + +**Problem:** People start comparing ideas or asking for feedback. +**Fix:** The afternoon sketch phase is silent. If someone asks a question, the Sprint Master says "Write it into your sketch." + +### Crazy 8s Feels Pointless + +**Problem:** People draw one idea 8 times or give up after 4 panels. +**Fix:** Before starting, show examples of good Crazy 8s. Emphasize that panels 5-8 often produce the best ideas because the obvious ones are exhausted. + +### Solution Sketches Are Too Vague + +**Problem:** Sketches show boxes labeled "content goes here" with no detail. +**Fix:** Remind the team: "Someone who was not in our sprint should be able to understand your sketch. Write real headlines, real button labels, real content." + +### Only Designers Produce Sketches + +**Problem:** Engineers and marketers opt out because they "cannot draw." +**Fix:** Share the non-designer tips above. Show examples of successful text-heavy, low-art sketches. The best sprint solutions often come from non-designers. + +### Perfectionism Kills the Solution Sketch + +**Problem:** Someone spends 90 minutes on a single beautiful panel. +**Fix:** Remind them: three panels, not one. The storyboard format forces breadth. Ugly but complete beats beautiful but incomplete. diff --git a/.agents/skills/design-sprint/references/wednesday.md b/.agents/skills/design-sprint/references/wednesday.md new file mode 100644 index 00000000..bece4531 --- /dev/null +++ b/.agents/skills/design-sprint/references/wednesday.md @@ -0,0 +1,268 @@ +# Wednesday: Decide on the Best Solution + +Wednesday transforms a gallery of individual sketches into a single plan the team will prototype and test. The day uses structured critique and voting to avoid design-by-committee and the loudest-voice-wins trap. The Decider makes the final call, the team builds a storyboard, and everyone leaves with a clear blueprint for Thursday's prototype. + +## Schedule Overview + +| Time | Exercise | Duration | +|------|----------|----------| +| 10:00 - 10:15 | Setup: Art Museum | 15 min | +| 10:15 - 10:45 | Silent review and heat map | 30 min | +| 10:45 - 12:00 | Speed critique (all sketches) | 75 min | +| 12:00 - 12:15 | Straw poll | 15 min | +| 12:15 - 12:30 | Supervote | 15 min | +| 12:30 - 1:30 | Lunch | 60 min | +| 1:30 - 2:00 | Rumble vs All-in-One decision | 30 min | +| 2:00 - 4:30 | Storyboard creation | 150 min | +| 4:30 - 5:00 | Storyboard review and confirmation | 30 min | + +## Art Museum Exercise + +### Setup (Before the Team Arrives) + +1. Tape each solution sketch to the wall at eye level, spaced evenly +2. Number each sketch (Sketch 1, Sketch 2, etc.) with a sticky note in the corner +3. Leave space between sketches for dot stickers +4. Place a stack of small dot stickers at each team member's seat + +### How to Run the Art Museum + +1. Everyone stands and walks along the wall, reviewing each sketch silently +2. No talking during this phase +3. Read each sketch carefully: title, panels, annotations +4. Place small dot stickers on any part of any sketch that catches your eye +5. You can use as many dots as you want +6. A dot means "this is interesting" (not "I vote for this") +7. Time: 20-30 minutes of silent review + +### Facilitator Tips + +- Play background music to reinforce the "no talking" rule +- If someone starts whispering, gently redirect: "Save it for the critique" +- Walk the room yourself to model the behavior +- Observe where clusters of dots form: these will drive the critique + +## Heat Map Review + +After silent voting, the wall should show clear heat maps: some sketches or sections will be covered in dots, others will have few. + +### Reading the Heat Map + +| Pattern | What It Means | +|---------|--------------| +| Dense cluster on one panel | Strong consensus on a specific idea | +| Dots spread evenly across a sketch | Generally interesting but no standout element | +| One sketch with very few dots | The idea did not resonate (or was hard to understand) | +| Same concept dotted across multiple sketches | A shared insight that multiple people reached independently | + +## Speed Critique + +### Purpose + +Give every sketch a fair, structured hearing without turning into an open debate. The Sprint Master controls the format strictly. + +### Process for Each Sketch (3 minutes per sketch) + +| Step | Who | What | Time | +|------|-----|------|------| +| 1. Narrate | Sprint Master | Walk through the sketch panel by panel: "Here the customer sees X, then they click Y, and this leads to Z" | 60 sec | +| 2. Call out | Team | Team members call out standout ideas. Sprint Master captures them on sticky notes above the sketch | 60 sec | +| 3. Concerns | Team | Quick objections or questions (not debate). Sprint Master notes them | 30 sec | +| 4. Creator speaks | Sketcher | The sketcher reveals themselves and clarifies anything missed (only if needed) | 30 sec | + +### Sprint Master Script for Narration + +Use this pattern for each panel: + +"In this sketch, titled [title], the customer starts by [describe Panel 1]. Then they [describe Panel 2]. And the result is [describe Panel 3]. I notice dots clustered around [specific element]." + +### Rules During Speed Critique + +- The sketcher stays silent until Step 4 +- No one says "I don't like this" without a specific reason +- The Sprint Master controls who speaks and when +- Capture ideas on sticky notes with one idea per note +- Stick to 3 minutes per sketch; use a timer + +## Straw Poll + +### Purpose + +A non-binding vote to reveal team preferences before the Decider makes the final call. + +### How to Run the Straw Poll + +1. Give each team member one large dot sticker (different color from the small dots) +2. Each person places their large dot on the sketch they think should be prototyped +3. Voting is simultaneous: count "3, 2, 1, vote" and everyone places their dot at once +4. After voting, go around the room. Each person explains their vote in one sentence +5. Record the vote tally on the whiteboard + +### Why One Sentence Matters + +The one-sentence explanation often reveals important reasoning: + +- "I picked Sketch 3 because it directly addresses our sprint question about trust" +- "I picked Sketch 5 because it is the simplest to prototype in one day" +- "I picked Sketch 1 because it solves the problem for both new and returning users" + +These explanations help the Decider make an informed final decision. + +## Supervote: The Decider's Final Call + +### How It Works + +1. The Decider receives three large dot stickers in a distinctive color (usually stars or a different color) +2. The Decider places their three dots on the sketch or sketches they want to prototype +3. The Decider can put all three on one sketch or spread them across multiple +4. The Decider's vote is final. No discussion, no override + +### Why the Decider Has This Power + +- Someone has to make the call, or the team compromises into mediocrity +- The Decider lives with the consequences, so they should choose +- It prevents endless negotiation +- It mirrors real organizational decision-making + +### What If the Team Disagrees? + +The Decider's choice stands. The sprint process trusts that testing on Friday will reveal whether the decision was right. If the Decider is wrong, the team will know by Friday afternoon, and only one week was invested. + +## Rumble vs All-in-One + +After the Supervote, the Sprint Master checks whether one or multiple sketches were selected. + +### All-in-One (Most Common) + +Use when the Decider's supervotes landed on one sketch or on compatible elements from multiple sketches. + +**Process:** +1. The winning sketch becomes the foundation +2. Pull in specific elements from other sketches that got dots or team support +3. Combine into a single concept + +### Rumble (Less Common) + +Use when the Decider's supervotes landed on two clearly different and incompatible approaches. + +**Process:** +1. Prototype both approaches (usually as branded competitors: "Concept A" and "Concept B") +2. Test both with users on Friday +3. Each approach gets its own storyboard panel sequence + +### Decision Criteria + +| Factor | All-in-One | Rumble | +|--------|-----------|--------| +| Decider selected one clear winner | Yes | No | +| Two strong but incompatible approaches | No | Yes | +| Limited prototyping resources | Yes | No | +| Team wants to resolve a strategic debate | No | Yes | +| You want more definitive Friday results | No | Yes | + +## Storyboard Creation + +### Purpose + +Translate the winning sketch into a step-by-step prototype blueprint. The storyboard tells Thursday's prototyping team exactly what to build, screen by screen. + +### Setup + +1. Draw a grid on the whiteboard: 10-15 empty rectangles arranged in rows +2. Each rectangle represents one frame (screen, interaction, or moment) +3. Number the frames 1 through 15 + +### Step-by-Step Process + +| Step | Duration | What Happens | +|------|----------|-------------| +| 1. Opening scene | 15 min | How does the customer first encounter the solution? (ad, email, search result, referral) | +| 2. Entry | 15 min | What is the first screen or interaction? (landing page, app home, signup) | +| 3. Core flow | 60 min | Walk through each step of the solution. One frame per screen or major interaction | +| 4. Success moment | 15 min | What does the customer see when they have succeeded? | +| 5. Review | 30 min | Walk through the entire storyboard. Does it make sense? Are there gaps? | + +### Storyboard Best Practices + +**Include:** +- Real headlines and copy (not "text goes here") +- Button labels +- Key images or illustrations (described, even if rough) +- Navigation elements +- Error states or edge cases (if they are part of the test) + +**Exclude:** +- Backend logic +- Features that will not be tested +- Multiple branching paths (pick one primary path) +- Detailed visual design (color, typography) + +### Example Storyboard: Online Grocery Delivery + +``` +Frame 1: Customer searches "grocery delivery [city]" +Frame 2: Google result: "Fresh groceries in 2 hours - [Brand]" +Frame 3: Landing page with value proposition and "Shop Now" button +Frame 4: Category browse: Produce, Dairy, Meat, Bakery +Frame 5: Product page: Organic Avocados, $4.99, "Add to Cart" +Frame 6: Cart summary with items, quantities, and total +Frame 7: Delivery time selection: "Today 2-4pm" or "Tomorrow 8-10am" +Frame 8: Checkout: address, payment (pre-filled if possible) +Frame 9: Order confirmation with estimated delivery time +Frame 10: SMS notification: "Your order is on its way" +Frame 11: Delivery photo: "Your groceries are at your door" +Frame 12: Follow-up: "How was your delivery? [Rate 1-5]" +``` + +### Common Storyboard Debates (and How to Resolve Them) + +| Debate | Resolution | +|--------|-----------| +| "Should we include signup?" | Only if signup is part of the test. If the sprint question is about the core experience, start after signup | +| "How detailed should the copy be?" | Detailed enough for the Writer on Thursday to know the intent. Not final copy | +| "What if the user goes off the path?" | Prototype the happy path. Note edge cases as sticky notes but do not storyboard them | +| "This needs 20 frames" | Reduce. If it takes more than 15, you are including too much. Focus on the core flow | + +## Wednesday Checklist + +- [ ] All sketches reviewed in Art Museum with heat map dots +- [ ] Speed critique completed for every sketch +- [ ] Straw poll conducted +- [ ] Decider has placed supervotes +- [ ] Rumble vs All-in-One decision made +- [ ] Storyboard drawn on whiteboard (10-15 frames) +- [ ] Storyboard includes real copy, not placeholders +- [ ] Everyone on the team understands and agrees with the storyboard +- [ ] Storyboard is photographed for Thursday reference + +## Common Wednesday Mistakes + +### Groupthink During the Art Museum + +**Problem:** Team members watch where others place dots and follow the crowd. +**Fix:** Spread the sketches far apart so it is harder to see others. Remind the team that dots mean "interesting," not "I vote for this." + +### Speed Critique Turns Into Debate + +**Problem:** One person argues for 10 minutes about why their approach is better. +**Fix:** The Sprint Master enforces the 3-minute timer per sketch. No rebuttals. Save opinions for the straw poll. + +### Decider Defers or Compromises + +**Problem:** The Decider says "Let's just combine everything into one" to avoid conflict. +**Fix:** Remind the Decider that Friday's test will validate the choice. Making a clear decision now is better than a watered-down compromise. A strong prototype of one idea beats a weak prototype that tries to do everything. + +### Storyboard Is Too Vague + +**Problem:** Frames show "main screen" and "results page" without specifics. +**Fix:** For each frame, ask: "If I handed this to a designer who was not in the room, could they build this screen?" If no, add more detail. + +### Storyboard Takes Too Long + +**Problem:** The team spends 4 hours on the storyboard and still is not done. +**Fix:** Time-box each section. The Sprint Master makes calls on unresolved details: "We are going with Option A. If it does not work on Friday, we will know." Move on. + +### Ignoring the Sprint Questions + +**Problem:** The storyboard drifts away from the sprint questions chosen on Monday. +**Fix:** Write the sprint questions above the storyboard. After each frame, ask: "Does this help answer our sprint question?" If a frame does not contribute to the test, cut it. diff --git a/.agents/skills/domain-driven-design/SKILL.md b/.agents/skills/domain-driven-design/SKILL.md new file mode 100644 index 00000000..7ee50a23 --- /dev/null +++ b/.agents/skills/domain-driven-design/SKILL.md @@ -0,0 +1,194 @@ +--- +name: domain-driven-design +description: 'Model software around the business domain using bounded contexts, aggregates, and ubiquitous language. Use when the user mentions "domain modeling", "bounded context", "aggregate root", "ubiquitous language", "anti-corruption layer", "context mapping", "domain events", "strategic design", "the code doesnt match the business", or "how do we split this big system". Also trigger when breaking a monolith into services, defining service boundaries, or aligning code structure with business processes. Covers entities vs value objects, domain events, and context mapping strategies. For architecture layers, see clean-architecture. For complexity, see software-design-philosophy.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Domain-Driven Design Framework + +Framework for tackling software complexity by modeling code around the business domain. The greatest risk in software is not technical failure -- it is building a model that does not reflect how the business actually works. + +## Core Principle + +**The model is the code; the code is the model.** Software should embody a deep, shared understanding of the business domain. When domain experts and developers speak the same language and that language is directly expressed in the codebase, complexity becomes manageable and the system evolves gracefully as the business changes. + +## Scoring + +**Goal: 10/10.** Score a domain model by awarding **1 point per satisfied row of the Quick Diagnostic** (7 rows) plus up to 3 points for depth: +1 if the Core Domain has a genuinely rich model (not just CRUD), +1 if invariants live inside aggregates rather than in services, +1 if the ubiquitous language is consistent across conversation, code, and tests. Bands: **9-10** = expert-readable names, explicit context boundaries with ACLs, small aggregates, behavior-rich entities, events for cross-aggregate flow, an identified Core Domain; **5-6** = some domain language but leaky boundaries or anemic objects; **<=3** = technical naming, one model for everything, logic scattered in services. Report the score and the specific diagnostic rows failing. + +## Framework + +### 1. Ubiquitous Language + +**Core concept:** A shared, rigorous language between developers and domain experts, used consistently in conversation, documentation, and code. When the language changes, the code changes -- and awkward naming in code feeds back into refining the language. + +**Why it works:** Ambiguity is the root cause of most modeling failures. When a developer says "order" and an expert means "purchase request," bugs are inevitable; a ubiquitous language forces every name in code to map to a concept the business recognizes and validates. + +**Key insights:** +- The language emerges from deep collaboration, not a glossary bolted on after the fact +- If a concept is hard to name, the model is likely wrong -- naming difficulty is a design signal +- Technical jargon (`DataProcessor` vs. `ClaimAdjudicator`) hides domain logic from the experts who could correct it +- Different bounded contexts may use the same word with different meanings -- and that is fine + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| Class/method naming | Name after domain concepts and verbs | `LoanApplication`, `policy.underwrite()` -- not `RequestHandler`, `process()` | +| Module structure | Organize by domain concept | `shipping/`, `billing/` -- not `controllers/`, `services/` | +| Code review | Reject technical-only names | Flag `Manager`, `Helper`, `Processor`, `Utils` as naming smells | + +See: [references/ubiquitous-language.md](references/ubiquitous-language.md) when running modeling sessions or maintaining a glossary -- covers how the language evolves and feeds back into code. + +### 2. Bounded Contexts and Context Mapping + +**Core concept:** A bounded context is an explicit boundary within which a particular domain model applies. The same word ("Customer") can mean different things in different contexts; context maps define the relationships and translation strategies between them. + +**Why it works:** Large systems that try to maintain a single unified model inevitably collapse into inconsistency. Bounded contexts accept that different parts of the business need different models; context maps manage the integration between them. + +**Key insights:** +- A bounded context is not a microservice -- it is a linguistic and model boundary that may contain multiple services +- Context boundaries often align with team boundaries (Conway's Law) +- The nine context mapping patterns describe political and technical relationships between teams +- Anti-Corruption Layer is the most important defensive pattern -- never let a foreign model leak into your core domain +- Shared Kernel couples two teams; keep it small and explicitly governed +- Start by mapping what exists (Big Ball of Mud), then define target boundaries + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| Service integration | Anti-Corruption Layer | Translate external API responses into your domain objects at the boundary | +| Legacy migration | Conformist / ACL | Wrap the legacy system behind an adapter that speaks your domain language | +| API design | Open Host Service + Published Language | Expose a well-documented REST API with a canonical schema | + +See: [references/bounded-contexts.md](references/bounded-contexts.md) for the nine mapping patterns and integration strategies. + +### 3. Entities, Value Objects, and Aggregates + +**Core concept:** Entities have identity that persists across state changes. Value Objects are defined entirely by their attributes and are immutable. Aggregates are clusters of entities and value objects with a single root that enforces consistency boundaries. + +**Why it works:** Without these distinctions, everything becomes a mutable, identity-bearing object -- tangled state, inconsistent updates, fragile concurrency. Aggregates draw the line: everything inside is guaranteed consistent; everything outside is eventually consistent. + +**Key insights:** +- Entity test: "Am I the same thing even if all my attributes change?" (a person changes name and address -- still the same person) +- Value Object test: "Am I defined only by my attributes?" (any $10 bill is interchangeable with another) +- Most things should be Value Objects, not Entities -- prefer immutability +- Keep aggregates small (one root plus a minimal cluster); reference other aggregates by ID, not object reference +- Immediate consistency only within an aggregate; design for eventual consistency between aggregates + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| Identity tracking | Entity with ID | `Order` identified by `orderId`, survives state changes | +| Immutable attributes | Value Object | `Address(street, city, zip)` -- replace, never mutate | +| Consistency boundary | Aggregate Root | `Order` is root; `OrderLine` items exist only through it | +| Concurrency control | Optimistic locking on root | Version field on `Order`; conflict if two edits race | + +See: [references/building-blocks.md](references/building-blocks.md) for aggregate design rules and consistency boundaries. + +### 4. Domain Events + +**Core concept:** A domain event captures something that happened in the domain that experts care about, named in past tense (`OrderPlaced`, `PaymentReceived`) -- a fact that has already occurred. + +**Why it works:** Domain events decouple cause from effect. When `OrderPlaced` is published, shipping, billing, and notifications each react independently without the ordering context knowing about them -- less coupling, eventual consistency, a natural audit trail. + +**Key insights:** +- Events are immutable facts -- once published, they cannot be changed or retracted +- Domain events are internal to a bounded context; integration events cross boundaries +- Events enable temporal decoupling: the producer does not wait for the consumer +- Event sourcing stores the full event history as the source of truth, deriving current state by replay +- Not every state change deserves an event -- only publish what the domain cares about + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| State transitions | Raise event on domain action | `order.place()` raises `OrderPlaced` | +| Cross-context integration | Publish integration event | `OrderPlaced` triggers `ShippingLabelRequested` in shipping context | +| Eventual consistency | Async event handlers | Inventory handler updates stock asynchronously after `OrderPlaced` | + +See: [references/domain-events.md](references/domain-events.md) for event naming, event sourcing, and integration events. + +### 5. Repositories and Factories + +**Core concept:** Repositories provide the illusion of an in-memory collection of domain objects, hiding persistence. Factories encapsulate complex creation logic so aggregates are always born in a valid state. + +**Why it works:** When persistence and assembly details leak into domain code, every storage change ripples through business rules and aggregates can be constructed in half-valid states. Repositories confine SQL/ORM concerns to infrastructure so the domain stays testable in memory; factories make the only path to an aggregate one that enforces its invariants, so an invalid instance is unrepresentable. + +**Key insights:** +- The Repository interface belongs in the domain layer; its implementation belongs in infrastructure +- Repository methods speak the ubiquitous language: `findPendingOrders()`, not `getByStatusCode(3)` +- Collection-oriented repositories mimic `add`/`remove`; persistence-oriented ones use `save` +- Factories are warranted for complex rules or multi-part assembly; a two-field Value Object just needs a constructor +- The Specification pattern encapsulates query criteria as domain objects: `OverdueInvoiceSpecification` + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| Data access abstraction | Repository interface | `OrderRepository.findByCustomer(customerId)` in domain; `PostgresOrderRepository` in infrastructure | +| Complex creation | Factory method | `Order.createFromQuote(quote)` validates and assembles from a `Quote` aggregate | +| Query encapsulation | Specification | `spec = OverdueBy(days=30); repo.findMatching(spec)` | + +See: [references/repositories-factories.md](references/repositories-factories.md) for Repository, Factory, and Specification patterns. + +### 6. Strategic Design and Distillation + +**Core concept:** Not all parts of a system are equally important. Strategic design identifies the Core Domain -- where competitive advantage lives -- and distinguishes it from Supporting Subdomains (necessary, not differentiating) and Generic Subdomains (commodity). + +**Why it works:** Applying the same rigor everywhere spreads your best talent thin and over-engineers commodity functionality. Identifying the Core Domain concentrates the best developers and deepest modeling where they matter most. + +**Key insights:** +- Core Domain: invest your best people and deepest modeling; Supporting: build, but don't over-engineer; Generic (auth, email, payments): buy or use open-source +- Distillation extracts and highlights the Core Domain from surrounding complexity +- A Domain Vision Statement is a one-page description of the Core Domain's value proposition +- Revisit what is "core" as the business evolves -- today's differentiator may become tomorrow's commodity + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| Build vs. buy | Classify subdomain type | Build custom pricing engine (core); use Stripe for payments (generic) | +| Team allocation | Best developers on Core Domain | Seniors model underwriting rules; juniors integrate the email service | +| Code organization | Separate core from generic | `domain/pricing/` (deep model) vs. `infrastructure/email/` (thin adapter) | + +See: [references/strategic-design.md](references/strategic-design.md) when deciding where to invest engineering effort -- subdomain classification and distillation techniques. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Technical names instead of domain language | Logic hidden behind `DataManager`; experts can't validate the model | Rename to domain terms (`ClaimAdjudicator`); if no domain term exists, the concept may be wrong | +| One model to rule them all | A single `Customer` class for billing, shipping, and marketing becomes bloated and contradictory | Bounded contexts: each gets its own `Customer` with only the attributes it needs | +| Giant aggregates | Concurrency conflicts, slow loads, transactional bottlenecks | Keep aggregates small; reference by ID; eventual consistency between them | +| Anemic domain model | Objects are data bags; rules scatter across services and duplicate | Move behavior into entities and value objects; services orchestrate only | +| No Anti-Corruption Layer | Foreign models leak in; code couples to external schemas | Wrap every external system behind a translation layer | +| Bounded context = microservice | Premature extraction; distributed complexity without benefit | A context is a model boundary, not a deployment unit; start with modules in a monolith | +| Skipping domain experts | Developers invent a model that doesn't match reality; expensive rework | Regular modeling sessions until experts say "yes, that is how it works" | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Can a domain expert read your class names and understand them? | Technical jargon hides the model | Rename classes, methods, events to ubiquitous language | +| Are bounded context boundaries explicitly defined? | Models bleed; same term means different things | Draw a context map; define boundaries and translations | +| Are aggregates small (one root + minimal cluster)? | Slow loads, concurrency issues | Split aggregates; reference by ID; accept eventual consistency | +| Do domain objects contain behavior, not just data? | Anemic model; logic scattered in services | Move business rules into entities and value objects | +| Are domain events used for cross-aggregate communication? | Tight coupling, synchronous chains | Introduce events; let aggregates react asynchronously | +| Is there an Anti-Corruption Layer at every external integration? | Foreign models pollute your domain | Add a translation layer at each boundary | +| Have you identified which subdomain is core? | Best talent spread thin | Classify subdomains; focus deep modeling on the Core Domain | + +## Further Reading + +For the complete methodology, patterns, and deeper insights: + +- [*"Domain-Driven Design: Tackling Complexity in the Heart of Software"*](https://www.amazon.com/Domain-Driven-Design-Tackling-Complexity-Software/dp/0321125215?tag=wondelai00-20) by Eric Evans + +## About the Author + +**Eric Evans** is a software design consultant and the originator of Domain-Driven Design, developed through work on large-scale systems in finance, insurance, and logistics. His 2003 book *Domain-Driven Design: Tackling Complexity in the Heart of Software* is one of the most influential software architecture books ever written, and he continues to evolve DDD through his consultancy, Domain Language. diff --git a/.agents/skills/domain-driven-design/references/bounded-contexts.md b/.agents/skills/domain-driven-design/references/bounded-contexts.md new file mode 100644 index 00000000..767f0f55 --- /dev/null +++ b/.agents/skills/domain-driven-design/references/bounded-contexts.md @@ -0,0 +1,203 @@ +# Bounded Contexts and Context Mapping + +A bounded context is the most important strategic pattern in Domain-Driven Design. It defines an explicit boundary within which a particular domain model is defined, consistent, and applicable. Context mapping describes the relationships between bounded contexts and the strategies for translating between them. + +## What Is a Bounded Context? + +A bounded context is not a module, a microservice, or a deployment unit -- though it may coincide with any of these. It is a linguistic boundary: within this boundary, every term has a single, precise meaning, and the model is internally consistent. + +### The Problem It Solves + +In any system of sufficient size, the same word means different things to different people: + +| Term | In Sales Context | In Shipping Context | In Billing Context | +|------|-----------------|--------------------|--------------------| +| Customer | A prospect or account with contact info and purchase history | A delivery address with receiving instructions | A billing entity with payment methods and credit terms | +| Product | A catalog item with descriptions, images, and pricing tiers | A physical item with weight, dimensions, and handling requirements | A line item with a price, tax category, and discount rules | +| Order | A quote or deal being negotiated | A shipment to be picked, packed, and dispatched | An invoice to be generated and collected | + +Trying to create a single `Customer` class that serves all three contexts produces a bloated, contradictory monstrosity with dozens of fields, most of which are irrelevant in any given use case. The bounded context pattern says: stop fighting this. Let each context have its own `Customer` model, optimized for its own needs. + +### Identifying Bounded Context Boundaries + +Boundaries emerge from several signals: + +**Linguistic signals:** +- When the same term means different things to different groups, those groups are in different contexts +- When conversations between groups require "translation" ("when you say X, do you mean Y?"), there is a boundary +- When a concept exists in one group but has no analog in another, the boundary is clear + +**Organizational signals:** +- Different teams owning different parts of the system +- Different departments with different processes and vocabulary +- Different regulatory requirements (e.g., PCI compliance for payments vs. HIPAA for patient data) + +**Technical signals:** +- Different data storage needs (relational vs. document vs. event store) +- Different consistency requirements (strong consistency for payments vs. eventual consistency for recommendations) +- Different rate of change (billing rules change quarterly; product catalog changes daily) + +### Context Size + +There is no formula for the right size of a bounded context. However, guidelines help: + +- **Too large:** If a single context contains concepts that do not cohesively relate, it is too large. A context that contains both "insurance underwriting" and "marketing campaign management" is probably two contexts. +- **Too small:** If you find yourself creating translation layers between closely related concepts that change together and are owned by the same team, you may have split too aggressively. +- **Rule of thumb:** A bounded context should be ownable by a single team (5-9 people). If a context requires multiple teams to modify, it is either too large or the team boundaries are wrong. + +## Context Mapping Patterns + +Context mapping describes how bounded contexts relate to each other. Eric Evans and the DDD community have identified nine primary patterns. Each represents a different political and technical relationship. + +### 1. Shared Kernel + +**What it is:** Two bounded contexts share a small subset of the model, typically a library of common types. Both teams co-own this shared code and must coordinate changes. + +**When to use:** When two closely collaborating teams need the same domain concept (e.g., a `Money` value object or a `DateRange` type) and the overhead of translation is not justified. + +**Risks:** Coupling. Any change to the shared kernel requires coordination between both teams. If not carefully managed, the shared kernel grows uncontrollably. + +**Rules:** +- Keep the shared kernel as small as possible -- value objects and basic types only +- Require explicit agreement (both teams) for any change +- Automated tests in both contexts must pass before any shared kernel change is merged +- Never put entities or aggregates in the shared kernel + +**Example:** Two contexts (billing and shipping) share a `Money(amount, currency)` value object and an `Address(street, city, state, zip, country)` value object. + +### 2. Customer-Supplier + +**What it is:** An upstream context (supplier) provides data or services that a downstream context (customer) depends on. The upstream team plans with the downstream team's needs in mind but has its own priorities. + +**When to use:** When one team produces something another team consumes, and there is a reasonable working relationship. The downstream team can influence the upstream team's roadmap but does not control it. + +**Example:** The Product Catalog team (upstream) provides product data to the Pricing team (downstream). The Pricing team requests new attributes when needed, and the Catalog team accommodates these requests in their planning. + +### 3. Conformist + +**What it is:** The downstream context conforms to the upstream context's model without translation. The downstream team accepts the upstream model as-is, even if it is not ideal. + +**When to use:** When the upstream team has no incentive or ability to accommodate the downstream team (e.g., a large external service, a legacy system, or a dominant upstream team), and the cost of building a translation layer exceeds the cost of conforming. + +**Risks:** Your model is constrained by someone else's design decisions. If the upstream model changes, your context must change too. + +**Example:** A startup integrating with a major ERP system may conform to the ERP's data model rather than building translation layers, accepting the ERP's concept of "customer" and "order" even if they do not perfectly fit. + +### 4. Anti-Corruption Layer (ACL) + +**What it is:** A translation layer that sits between the downstream context and the upstream context, converting the upstream model into the downstream context's own domain language. The ACL protects the downstream model from being polluted by foreign concepts. + +**When to use:** When you need to integrate with a system whose model does not fit yours, and you cannot afford to let that foreign model leak into your domain. This is the most important defensive pattern in DDD. + +**Structure:** +``` +Your Domain Layer <--> ACL (Adapters + Translators) <--> External System +``` + +The ACL contains: +- **Adapters** that handle the technical protocol (HTTP, gRPC, message queue) +- **Translators** that convert external model objects into your domain objects +- **Facades** that present a clean interface to your domain layer + +**Example:** Integrating with a legacy mainframe that represents customers as `CUST_REC` with fields like `CUST_NM`, `CUST_ADDR1`. The ACL translates this into your domain's `Customer(name: PersonName, address: Address)` value objects. + +### 5. Open Host Service (OHS) + +**What it is:** An upstream context exposes a well-defined, documented protocol (API, message format) that downstream contexts can integrate with. The upstream team provides a stable, versioned interface designed for general consumption. + +**When to use:** When an upstream context serves multiple downstream consumers and cannot tailor its interface to each one. The OHS provides a standard integration point. + +**Characteristics:** +- Versioned API with backward compatibility guarantees +- Documentation and contracts (OpenAPI, protobuf schemas, JSON Schema) +- The interface is deliberately designed for external consumption, not a direct exposure of the internal model + +**Example:** An Identity Provider exposes an OAuth 2.0 / OpenID Connect API. Any downstream context can integrate using the standard protocol without knowing the internal user model. + +### 6. Published Language + +**What it is:** A well-documented, shared language (schema, format, protocol) used for communication between contexts. Often paired with Open Host Service. + +**When to use:** When multiple contexts need to exchange data and a standard format prevents each integration from inventing its own. + +**Examples:** +- Industry-standard formats: HL7 for healthcare, SWIFT for banking, EDI for supply chain +- Internal schemas: a company-wide JSON schema for events published on a shared message bus +- Protocol Buffers or Avro schemas for service-to-service communication + +### 7. Separate Ways + +**What it is:** Two contexts decide not to integrate at all. Each builds its own solution independently, even if there is some overlap. + +**When to use:** When the cost of integration (coordination, translation, coupling) exceeds the cost of duplication. Sometimes it is cheaper and simpler for two teams to build their own `Address` validation than to share one. + +**Signals that Separate Ways is appropriate:** +- The integration would be trivial functionality on both sides +- The teams are in different organizations with different release cycles +- The shared functionality is not core to either context + +### 8. Big Ball of Mud + +**What it is:** A system with no clear boundaries, where models are entangled and concepts leak everywhere. This is not a recommended pattern -- it is a recognition of reality. Many existing systems are Big Balls of Mud. + +**When to use (as a label):** When mapping an existing landscape, some systems simply are Big Balls of Mud. Acknowledging this is the first step toward improvement. Drawing a boundary around the mud and treating it as a single (messy) context allows you to build clean contexts alongside it, protected by an ACL. + +**Migration strategy:** +1. Draw a boundary around the entire mudball +2. Build new functionality in a clean bounded context +3. Protect the new context with an ACL against the mudball +4. Gradually extract functionality from the mud into clean contexts + +### 9. Partnership + +**What it is:** Two contexts evolve together with mutual coordination. Both teams jointly plan features and synchronize releases. Neither dominates. + +**When to use:** When two contexts are tightly coupled in the domain and both teams are committed to evolving together. More intimate than Customer-Supplier; both teams have equal say. + +**Risks:** Requires strong coordination discipline. If one team slips, both are affected. + +**Example:** A checkout context and a payment processing context that must evolve in lockstep when payment methods change. + +## Team Relationships and Context Boundaries + +### Conway's Law in Practice + +Conway's Law states that systems mirror the communication structures of the organizations that build them. In DDD, this is not a warning -- it is a design tool: + +- **Align context boundaries with team boundaries.** If one team owns billing and another owns shipping, these should be separate bounded contexts. +- **If two teams must share a context, expect friction.** Either split the context or merge the teams. +- **Cross-team integration should happen at context boundaries,** using well-defined mapping patterns, not through shared code or databases. + +### Choosing the Right Pattern + +| Situation | Recommended Pattern | +|-----------|-------------------| +| Two teams with a good relationship and shared concepts | Shared Kernel (kept small) or Customer-Supplier | +| Integrating with a system you do not control | Anti-Corruption Layer | +| Exposing your context to many consumers | Open Host Service + Published Language | +| Integrating with a hostile or unresponsive upstream | Conformist (if cost is low) or Separate Ways | +| Legacy system with no clear model | Big Ball of Mud (label it) + ACL around it | +| Two teams that must evolve in lockstep | Partnership | +| Integration cost exceeds duplication cost | Separate Ways | + +### Drawing a Context Map + +A context map is a visual representation of all bounded contexts and their relationships. It should include: + +1. **Every bounded context** drawn as a labeled box +2. **The relationships between them** using the patterns above (arrows show upstream/downstream) +3. **The translation mechanism** (ACL, OHS, Shared Kernel) +4. **Team ownership** for each context +5. **The Big Balls of Mud** explicitly labeled + +The context map is a communication tool. It should be understandable by both developers and non-technical stakeholders. Keep it on a whiteboard or in a shared diagram that the team references and updates regularly. + +### When Boundaries Change + +Context boundaries are not permanent. They evolve as the business and team structure change: + +- **Splitting:** A context grows too large for one team; split it along natural seams and introduce a mapping pattern between the new contexts. +- **Merging:** Two small contexts owned by the same team with heavy inter-communication; merge them and eliminate the translation overhead. +- **Reclassifying:** A context that was Generic Subdomain becomes Core Domain as business strategy shifts; increase investment and modeling rigor. + +The key is to make boundaries explicit and intentional, so that when they need to change, the change is a deliberate design decision rather than an accidental drift. diff --git a/.agents/skills/domain-driven-design/references/building-blocks.md b/.agents/skills/domain-driven-design/references/building-blocks.md new file mode 100644 index 00000000..424ceee9 --- /dev/null +++ b/.agents/skills/domain-driven-design/references/building-blocks.md @@ -0,0 +1,234 @@ +# Building Blocks: Entities, Value Objects, and Aggregates + +The tactical building blocks of Domain-Driven Design provide a vocabulary for structuring domain models. Entities, Value Objects, and Aggregates are the three most critical patterns. Getting them right determines whether a domain model is expressive and maintainable or bloated and fragile. + +## Entities + +An Entity is a domain object defined by its identity rather than its attributes. An entity persists across time and state changes -- it is the "same thing" even when everything about it changes. + +### The Identity Test + +Ask: "If all the attributes change, is it still the same thing?" + +- A **person** changes name, address, phone number, job, and appearance -- still the same person. **Entity.** +- A **bank account** changes its balance daily -- still the same account. **Entity.** +- A **$10 bill** is interchangeable with any other $10 bill. **Not an entity -- Value Object.** + +### Identity Strategies + +| Strategy | How It Works | When to Use | +|----------|-------------|-------------| +| Natural key | Use a real-world identifier (SSN, ISBN, VIN) | When a stable, unique external identifier exists | +| Surrogate key | Generate a synthetic ID (UUID, auto-increment) | When no natural key exists or the natural key can change | +| Composite key | Combine multiple attributes | When identity is defined by a relationship (e.g., student + course = enrollment) | + +**Prefer UUIDs over auto-increment** for distributed systems. UUIDs can be generated anywhere without coordination; auto-increment requires a central authority. + +### Entity Design Rules + +1. **Identity is immutable.** Once assigned, an entity's identity never changes. If the "identity" can change, it is not really the identity. +2. **Entities are mutable.** Unlike Value Objects, entities change state over time. An `Order` moves from `Pending` to `Confirmed` to `Shipped`. +3. **Equality is based on identity.** Two `Order` objects with the same `orderId` are the same order, regardless of other attribute differences. +4. **Entities have a lifecycle.** They are created, go through state transitions, and may eventually be archived or deleted. +5. **Put behavior on entities.** An entity is not a data container. `order.addItem(product, quantity)` belongs on the `Order` entity, not in an `OrderService`. + +### Common Entity Pitfalls + +- **Over-identification.** Making everything an entity when most things should be Value Objects. Ask the identity test for every class. +- **Anemic entities.** Entities with only getters and setters. If all behavior is in services, the entity is a data bag. +- **Identity leakage.** Exposing database primary keys as domain identity. Use domain-meaningful identifiers (`orderNumber`) rather than technical ones (`id: 42`). + +## Value Objects + +A Value Object is a domain object defined entirely by its attributes. It has no identity -- two Value Objects with the same attributes are interchangeable. Value Objects are immutable: you do not change a Value Object; you replace it. + +### The Attribute Test + +Ask: "Is it defined by what it is, not which one it is?" + +- A **mailing address** (123 Main St, Springfield, IL 62704) -- defined by its attributes. Two objects with the same street, city, state, zip are the same address. **Value Object.** +- A **money amount** ($49.99 USD) -- defined by amount and currency. **Value Object.** +- A **date range** (Jan 1 - Dec 31) -- defined by start and end. **Value Object.** +- A **color** (#FF5733) -- defined by its hex value. **Value Object.** + +### Why Value Objects Matter + +Value Objects are the unsung heroes of domain models. Most developers default to entities for everything, but **the majority of concepts in a well-designed domain model should be Value Objects.** + +**Benefits of Value Objects:** + +| Benefit | Explanation | +|---------|-------------| +| Immutability | No shared mutable state; safe to pass around, cache, and use in concurrent code | +| Side-effect-free behavior | Methods return new Value Objects rather than mutating state; easy to reason about | +| Self-validation | A Value Object validates itself on creation; an invalid Value Object can never exist | +| Equality by value | `Money(100, "USD") == Money(100, "USD")` regardless of object reference | +| Expressiveness | `Money` instead of `BigDecimal`; `EmailAddress` instead of `String`; domain meaning is encoded in the type | + +### Value Object Design Rules + +1. **Immutable.** All fields are set at construction and never change. No setters. +2. **Self-validating.** A `Money` object with a negative amount or null currency should throw on construction. If it exists, it is valid. +3. **Equality by attributes.** Override `equals()` and `hashCode()` to compare all attributes. +4. **Side-effect-free methods.** `money.add(other)` returns a new `Money`; it does not mutate the original. +5. **Replace, don't modify.** To change an address, create a new `Address` and assign it. `customer.changeAddress(newAddress)`. + +### Common Value Objects + +| Value Object | Replaces | Why It Is Better | +|-------------|---------|------------------| +| `Money(amount, currency)` | `BigDecimal` | Prevents currency mismatch errors; encapsulates rounding rules | +| `EmailAddress(value)` | `String` | Validates format on construction; impossible to have invalid email in the system | +| `DateRange(start, end)` | Two `Date` fields | Enforces `start <= end`; contains overlap/contains logic | +| `Address(street, city, state, zip)` | Multiple String fields | Groups related data; validates as a unit | +| `Quantity(value, unit)` | `int` or `double` | Prevents unit mismatch (adding kilograms to liters) | +| `PhoneNumber(countryCode, number)` | `String` | Validates format; normalizes representation | + +### When to Use Value Objects vs. Entities + +| Signal | Entity | Value Object | +|--------|--------|-------------| +| Needs to be tracked over time | Yes | No | +| Has a lifecycle (created, modified, archived) | Yes | No -- replaced, not modified | +| Two instances with same attributes are different things | Yes | No -- they are the same thing | +| Immutability is natural | No | Yes | +| Appears in the model as a measurement, description, or attribute | No | Yes | + +**Rule of thumb:** If in doubt, make it a Value Object. You can always promote it to an Entity later if identity becomes important. Going the other direction (demoting an Entity to a Value Object) is much harder. + +## Aggregates + +An Aggregate is a cluster of domain objects (entities and value objects) treated as a single unit for data changes. Every aggregate has a single root entity -- the Aggregate Root -- through which all external access occurs. + +### Why Aggregates Exist + +Without aggregates, any object in the system can hold a reference to any other object and modify it directly. This creates an impossibly tangled web of dependencies where enforcing business invariants (rules that must always be true) becomes a nightmare. + +Aggregates solve this by drawing a boundary: +- **Inside the boundary:** Strong consistency. All invariants are enforced within a single transaction. +- **Outside the boundary:** Eventual consistency. Changes propagate via domain events or polling. + +### Aggregate Design Rules + +Eric Evans and Vaughn Vernon established these rules, refined by the DDD community: + +#### Rule 1: Protect Business Invariants Inside the Aggregate + +An invariant is a rule that must always be true. Example: "An order's total must equal the sum of its line items." This invariant involves `Order` and `OrderLineItem`. Both belong in the same aggregate because the invariant spans both. + +| If the invariant spans... | Then... | +|--------------------------|---------| +| A single entity | That entity is its own aggregate | +| An entity and its closely related objects | They form one aggregate | +| Two independently identifiable things | They are separate aggregates; enforce the rule via eventual consistency or a domain event | + +#### Rule 2: Small Aggregates + +Large aggregates cause: +- **Concurrency conflicts.** Two users editing different parts of the same large aggregate will conflict. +- **Performance problems.** Loading a large aggregate means loading everything it contains. +- **Transaction scope bloat.** Larger transaction scope means longer locks and more contention. + +**Ideal aggregate size:** One root entity, a small set of value objects, and occasionally a small collection of child entities (e.g., `Order` with `OrderLineItems`). + +**Anti-pattern:** An `Organization` aggregate that contains `Departments` which contain `Employees` which contain `Assignments`. This is too large. `Employee` should be its own aggregate, referencing `Organization` and `Department` by ID. + +#### Rule 3: Reference Other Aggregates by ID Only + +Do not hold direct object references to other aggregates. Instead, store only the identifier: + +**Wrong:** +``` +class Order { + Customer customer; // Direct reference to another aggregate +} +``` + +**Right:** +``` +class Order { + CustomerId customerId; // Reference by ID only +} +``` + +**Why:** Direct references create tight coupling, prevent independent scaling, and make it impossible to enforce aggregate boundaries. With ID references, each aggregate can be loaded, stored, and cached independently. + +#### Rule 4: Use Eventual Consistency Across Aggregate Boundaries + +When one aggregate's action should trigger a change in another aggregate, do not try to update both in the same transaction. Instead: + +1. The first aggregate performs its action and publishes a domain event +2. An event handler picks up the event and modifies the second aggregate in a separate transaction + +**Example:** +- `Order.place()` publishes `OrderPlaced` event +- `InventoryHandler` receives `OrderPlaced` and calls `inventory.reserve(items)` +- These are two separate transactions + +### Choosing Aggregate Boundaries + +#### Start with the Invariant + +Identify every business invariant. Group objects that participate in the same invariant into the same aggregate. + +**Example invariants:** +| Invariant | Objects Involved | Aggregate | +|-----------|-----------------|-----------| +| "An order total must equal the sum of its lines" | Order, OrderLineItem | Order aggregate | +| "A product must have at least one category" | Product, Category | Product aggregate (Category is a value object or ID reference) | +| "An account balance must never go below the overdraft limit" | Account | Account aggregate (single entity) | +| "A reservation cannot overlap with another for the same room" | Reservation | Reservation aggregate (overlap check is a domain service or repository query, not a cross-aggregate invariant) | + +#### The Transaction Boundary Test + +Ask: "Must these two changes happen atomically, or can they happen with a small delay?" + +- If **atomically**: same aggregate +- If **small delay is acceptable**: separate aggregates with eventual consistency + +Most of the time, a small delay is acceptable. Humans rarely need true atomicity outside of financial transactions. + +### Aggregate Root Pattern + +The Aggregate Root is the single entity through which all external interaction with the aggregate occurs: + +**Rules for the root:** +1. External objects may only hold references to the root, never to internal entities +2. All changes to the aggregate go through the root's methods +3. The root enforces all aggregate invariants +4. The root controls the lifecycle of all internal objects +5. Delete the root and everything inside the aggregate is deleted + +**Example:** +``` +// External code interacts only with Order (the root) +order.addLineItem(product, quantity, price) +order.removeLineItem(lineItemId) +order.calculateTotal() + +// LineItems are never accessed directly from outside +// WRONG: lineItem.changeQuantity(5) +// RIGHT: order.changeLineItemQuantity(lineItemId, 5) +``` + +### Common Aggregate Mistakes + +| Mistake | Consequence | Fix | +|---------|------------|-----| +| Making the entire object graph one aggregate | Concurrency nightmares, slow loading | Split into multiple aggregates; reference by ID | +| Holding direct references to other aggregates | Tight coupling; cannot enforce boundaries | Replace with ID references | +| Updating multiple aggregates in one transaction | Distributed lock contention; scaling bottleneck | Use domain events for cross-aggregate consistency | +| Putting all logic in services instead of the aggregate root | Anemic aggregate; invariants not enforced | Move invariant-enforcing logic into the aggregate root | +| Creating aggregates based on database tables | Data model drives domain model (backward) | Design aggregates from domain invariants, then map to persistence | + +## Putting It All Together + +A well-designed domain model has this structure: + +1. **Value Objects** form the majority of types -- measurements, descriptions, identifiers, small composites +2. **Entities** represent things with identity and lifecycle -- fewer than you think +3. **Aggregates** cluster related entities and value objects behind a root -- enforcing consistency boundaries +4. **References between aggregates** are by ID only -- enabling independent evolution +5. **Cross-aggregate consistency** is achieved through domain events -- eventual consistency is the default + +The result is a model that is expressive (reads like the business), consistent (invariants are enforced), and scalable (aggregates are independent units of consistency, persistence, and caching). diff --git a/.agents/skills/domain-driven-design/references/domain-events.md b/.agents/skills/domain-driven-design/references/domain-events.md new file mode 100644 index 00000000..d67e7c32 --- /dev/null +++ b/.agents/skills/domain-driven-design/references/domain-events.md @@ -0,0 +1,264 @@ +# Domain Events + +A domain event represents something that happened in the domain that domain experts care about. Events are named in past tense, are immutable facts, and serve as the primary mechanism for decoupling bounded contexts and achieving eventual consistency across aggregate boundaries. + +## What Domain Events Are + +A domain event captures a meaningful occurrence in the business domain. "Meaningful" means that a domain expert would recognize it as significant -- not just a technical state change. + +### Domain Events vs. Technical Events + +| Domain Event | Technical Event | Why It Matters | +|-------------|----------------|----------------| +| `OrderPlaced` | `RowInserted` | The domain expert cares about orders being placed; they do not care about database rows | +| `PaymentReceived` | `WebhookProcessed` | The business reacts to payments; the webhook is an implementation detail | +| `ClaimDenied` | `StatusUpdated` | Denial triggers business processes (appeals, notifications); a status update triggers nothing meaningful | +| `InventoryDepleted` | `CountReachedZero` | The business has specific procedures for depleted inventory; zero is just a number | + +### The Litmus Test + +Ask a domain expert: "Would you care if this happened?" If yes, it is a domain event. If they shrug, it is a technical event that belongs in infrastructure, not in the domain model. + +## Naming Domain Events + +### The Past-Tense Rule + +Domain events are always named in past tense because they represent facts that have already occurred. By the time anyone processes the event, the thing has already happened. + +**Correct naming:** +- `OrderPlaced` -- an order was placed +- `PaymentReceived` -- a payment was received +- `ShipmentDispatched` -- a shipment was dispatched +- `AccountSuspended` -- an account was suspended +- `PolicyRenewed` -- a policy was renewed + +**Incorrect naming:** +- `PlaceOrder` -- this is a command, not an event +- `OrderPlacing` -- this implies the action is in progress +- `OrderEvent` -- too generic; what happened? +- `OrderUpdate` -- "update" is not a domain concept; what specifically changed? + +### Naming Specificity + +Be specific about what happened. Vague event names create the same problems as vague method names -- consumers cannot understand what occurred without reading the payload. + +| Vague | Specific | Why Specific Is Better | +|-------|----------|----------------------| +| `OrderChanged` | `OrderItemAdded`, `OrderItemRemoved`, `OrderAddressChanged` | Different changes trigger different business reactions | +| `UserUpdated` | `UserEmailVerified`, `UserPasswordChanged`, `UserProfileCompleted` | A password change requires a security audit; a profile completion triggers onboarding flow | +| `PaymentProcessed` | `PaymentAuthorized`, `PaymentCaptured`, `PaymentRefunded` | Authorization and capture are distinct business steps with different downstream effects | + +### Event Naming Conventions + +Adopt a consistent naming pattern across the codebase: + +``` +{AggregateType}{DomainAction} +``` + +Examples: +- `OrderPlaced`, `OrderCancelled`, `OrderFulfilled` +- `InvoiceSent`, `InvoicePaid`, `InvoiceOverdue` +- `MemberRegistered`, `MemberSuspended`, `MemberReinstated` + +## Event Structure + +A well-designed domain event contains: + +| Field | Purpose | Example | +|-------|---------|---------| +| `eventId` | Unique identifier for this specific event occurrence | `uuid("a1b2c3d4...")` | +| `eventType` | The name of the event | `"OrderPlaced"` | +| `occurredAt` | When the event happened | `"2024-03-15T14:30:00Z"` | +| `aggregateId` | The ID of the aggregate that produced the event | `orderId: "ORD-12345"` | +| `aggregateType` | The type of aggregate | `"Order"` | +| `payload` | The domain-relevant data | `{ customerId, items, total, shippingAddress }` | +| `metadata` | Technical metadata (correlation ID, causation ID, user ID) | `{ correlationId, userId }` | + +### What Goes in the Payload + +Include enough data for consumers to react without calling back to the producer: + +**Too little:** +```json +{ "orderId": "ORD-12345" } +``` +Every consumer must call back to the Order service to get details. This creates coupling and latency. + +**Too much:** +```json +{ "order": { /* entire order aggregate serialized */ } } +``` +This bloats messages, exposes internal model details, and creates tight coupling to the aggregate structure. + +**Just right:** +```json +{ + "orderId": "ORD-12345", + "customerId": "CUST-789", + "items": [ + { "productId": "PROD-1", "quantity": 2, "unitPrice": 29.99 } + ], + "totalAmount": 59.98, + "currency": "USD", + "shippingAddress": { "city": "Springfield", "state": "IL" } +} +``` +Enough for most consumers to react; detailed enough to avoid callbacks for common cases. + +## Publishing Domain Events + +### Where Events Are Raised + +Domain events are raised within the aggregate, as part of the domain operation that caused them: + +``` +class Order: + def place(self): + self._validate_can_be_placed() + self.status = OrderStatus.PLACED + self._raise_event(OrderPlaced( + order_id=self.id, + customer_id=self.customer_id, + items=self.items, + total=self.total + )) +``` + +The aggregate records the event internally. An infrastructure mechanism (event dispatcher, outbox pattern) publishes it after the aggregate is persisted. + +### The Outbox Pattern + +The most reliable way to publish domain events is the transactional outbox: + +1. Within the same database transaction that persists the aggregate, insert the event into an `outbox` table +2. A separate process (poller or CDC -- Change Data Capture) reads from the outbox and publishes to the message broker +3. After successful publication, mark the outbox entry as published + +**Why this matters:** If you publish the event and then save the aggregate, the save might fail -- you published a lie. If you save the aggregate and then publish, the publish might fail -- the event is lost. The outbox pattern ties both operations to the same database transaction. + +### Delivery Guarantees + +| Guarantee | Meaning | Implementation | +|-----------|---------|----------------| +| At-most-once | Events may be lost but never duplicated | Fire-and-forget; no outbox; acceptable for non-critical events | +| At-least-once | Events are never lost but may be duplicated | Outbox pattern with retry; consumers must be idempotent | +| Exactly-once | Events are delivered exactly once | Practically impossible in distributed systems; achieve via at-least-once + idempotent consumers | + +**At-least-once with idempotent consumers** is the standard approach. Design every event handler to be safe to run multiple times with the same event. + +## Domain Events for Cross-Context Integration + +### Internal vs. Integration Events + +| Aspect | Domain Event (Internal) | Integration Event (External) | +|--------|------------------------|------------------------------| +| Scope | Within a bounded context | Across bounded contexts | +| Audience | Event handlers in the same context | Other teams' services | +| Schema | Can change freely with the model | Must be versioned and backward-compatible | +| Naming | Uses internal ubiquitous language | Uses published language (shared schema) | +| Transport | In-process event bus or same database | Message broker (Kafka, RabbitMQ, SNS) | + +### Translation at the Boundary + +When a domain event crosses a bounded context boundary, it should be translated into an integration event that uses the published language: + +1. **Order context** raises `OrderPlaced` (domain event, internal language) +2. **Anti-corruption layer** translates to `PurchaseCompleted` (integration event, published language) +3. **Shipping context** receives `PurchaseCompleted` and translates to `ShipmentRequested` (domain event, shipping language) + +This translation prevents internal model changes from breaking external consumers. + +### Event-Driven Architecture Patterns + +#### Event Notification + +The event carries minimal data ("something happened") and consumers call back for details. Simplest pattern but creates temporal coupling. + +#### Event-Carried State Transfer + +The event carries all the data consumers need. Consumers maintain their own local copy of relevant data, reducing coupling but increasing event size and requiring consumers to maintain projections. + +#### Event Sourcing + +Events are the source of truth. Current state is derived by replaying events. This is the most powerful and most complex pattern. + +## Event Sourcing + +Event sourcing stores the complete history of state changes as an ordered sequence of events. Instead of storing only the current state ("account balance is $1,000"), the system stores every event that led to that state ("deposited $500, deposited $800, withdrew $300"). + +### When to Use Event Sourcing + +| Good Fit | Poor Fit | +|----------|----------| +| Audit requirements (financial, medical, legal) | Simple CRUD with no audit needs | +| Complex domain with many state transitions | Domains with few state changes | +| Need to answer "how did we get here?" | Only need current state | +| Need to rebuild state at any point in time | No temporal query requirements | +| High-value domain events that are worth preserving | High-volume, low-value data (telemetry) | + +### Event Sourcing Mechanics + +**Storing events:** +``` +Stream: Order-12345 + 1: OrderCreated { customerId, items } + 2: PaymentAuthorized { paymentId, amount } + 3: OrderConfirmed { confirmedAt } + 4: ItemShipped { trackingNumber, items } + 5: OrderDelivered { deliveredAt, signedBy } +``` + +**Rebuilding state:** +``` +currentState = OrderCreated.apply(emptyOrder) +currentState = PaymentAuthorized.apply(currentState) +currentState = OrderConfirmed.apply(currentState) +currentState = ItemShipped.apply(currentState) +currentState = OrderDelivered.apply(currentState) +``` + +**Snapshots** optimize performance: periodically save the current state so you do not need to replay from the beginning every time. + +### Event Sourcing Challenges + +| Challenge | Solution | +|-----------|----------| +| Event schema evolution | Use upcasters to transform old events into the current schema; never delete old events | +| Performance with long event streams | Snapshots at regular intervals; read models for queries | +| Complexity | Only use event sourcing for aggregates where it provides clear value; not everything needs to be event-sourced | +| Debugging | Event logs provide excellent debugging and auditing; invest in tooling to browse and replay events | + +## Patterns for Event Handling + +### Idempotent Handlers + +Every event handler must be safe to execute multiple times with the same event. Strategies: + +- **Idempotency key:** Store processed event IDs; skip duplicates +- **Idempotent operations:** Design the operation itself to be naturally idempotent (e.g., "set balance to X" instead of "add Y to balance") +- **Conditional writes:** Use optimistic concurrency (version checks) to prevent double-application + +### Ordering Guarantees + +Events from the same aggregate should be processed in order. Events from different aggregates have no ordering guarantees. Design consumers accordingly: + +- Partition by aggregate ID in the message broker (Kafka partition key = aggregate ID) +- Handle out-of-order events gracefully (check event version, buffer and reorder if needed) + +### Dead Letter Handling + +Events that repeatedly fail to process should be routed to a dead letter queue for investigation. Never silently drop failed events. Monitor dead letter queues actively. + +### Sagas and Process Managers + +Long-running business processes that span multiple aggregates or bounded contexts can be coordinated using sagas: + +1. `OrderPlaced` triggers the saga +2. Saga sends `ReserveInventory` command +3. `InventoryReserved` event continues the saga +4. Saga sends `AuthorizePayment` command +5. `PaymentAuthorized` event continues the saga +6. If any step fails, the saga sends compensating commands (`ReleaseInventory`, `RefundPayment`) + +Sagas maintain their own state and react to events. They do not hold locks -- they coordinate through events and compensating actions. diff --git a/.agents/skills/domain-driven-design/references/repositories-factories.md b/.agents/skills/domain-driven-design/references/repositories-factories.md new file mode 100644 index 00000000..0ebee60d --- /dev/null +++ b/.agents/skills/domain-driven-design/references/repositories-factories.md @@ -0,0 +1,353 @@ +# Repositories and Factories + +Repositories and Factories are infrastructure-facing patterns in Domain-Driven Design that separate domain logic from persistence and object creation concerns. The Repository provides the illusion of an in-memory collection of aggregates. The Factory encapsulates complex creation logic. Together, they keep the domain model clean and focused on business rules. + + +## Table of Contents +1. [The Repository Pattern](#the-repository-pattern) +2. [The Factory Pattern](#the-factory-pattern) +3. [The Specification Pattern](#the-specification-pattern) +4. [Ports and Adapters Relationship](#ports-and-adapters-relationship) + +--- + +## The Repository Pattern + +A Repository mediates between the domain and data mapping layers, acting like an in-memory collection of domain objects. Domain code uses the repository to obtain aggregates without knowing how they are stored, queried, or reconstructed. + +### Why Repositories Exist + +Without repositories, domain logic becomes tangled with data access: + +``` +// Without repository -- domain logic polluted with SQL +def approve_claim(claim_id): + row = db.execute("SELECT * FROM claims WHERE id = ?", claim_id) + claim = Claim(row['id'], row['status'], row['amount']) + claim.approve() + db.execute("UPDATE claims SET status = ? WHERE id = ?", claim.status, claim.id) +``` + +``` +// With repository -- domain logic is clean +def approve_claim(claim_id): + claim = claim_repository.find_by_id(claim_id) + claim.approve() + claim_repository.save(claim) +``` + +The second version is readable by a domain expert. The first is not. + +### Repository Interface Design + +The repository interface belongs in the domain layer. It speaks the ubiquitous language: + +**Good repository methods:** +- `find_by_id(order_id)` -- straightforward identity lookup +- `find_pending_orders()` -- uses domain language ("pending") +- `find_by_customer(customer_id)` -- domain-meaningful query +- `find_overdue_invoices(as_of_date)` -- business concept in the method name + +**Bad repository methods:** +- `get_by_status_code(3)` -- magic number; what is status 3? +- `query(sql_string)` -- leaks persistence technology into the domain +- `find_all_with_joins()` -- technical concern, not domain language +- `get_by_column("status", "PENDING")` -- generic data access, not domain query + +### Collection-Oriented vs. Persistence-Oriented Repositories + +Eric Evans described two flavors of repository, each modeling a different metaphor: + +#### Collection-Oriented Repository + +Models the repository as an in-memory collection. You add objects to it and remove objects from it. Changes to retrieved objects are automatically tracked and persisted (like JPA/Hibernate managed entities). + +``` +interface OrderRepository: + add(order) # Like collection.add() + remove(order) # Like collection.remove() + find_by_id(id) # Like collection.find() + # No explicit save() -- changes to retrieved objects are auto-tracked +``` + +**Best with:** ORMs that support change tracking (JPA/Hibernate, Entity Framework). + +**Advantages:** Clean domain model; changes feel natural; no explicit save calls. + +**Disadvantages:** "Magic" change tracking can surprise developers; harder to reason about when persistence happens. + +#### Persistence-Oriented Repository + +Models the repository as a storage mechanism. You explicitly save objects and the repository does not track changes automatically. + +``` +interface OrderRepository: + save(order) # Explicit persist/update + delete(order_id) # Explicit remove + find_by_id(id) # Retrieve + # Must call save() explicitly after making changes +``` + +**Best with:** Frameworks without change tracking (most non-ORM approaches, event sourcing, document stores). + +**Advantages:** Explicit control over when persistence happens; no surprises; easier to test. + +**Disadvantages:** Must remember to call save(); risk of losing changes if save is forgotten. + +**Which to choose:** If your persistence technology offers change tracking and your team is comfortable with it, use collection-oriented. Otherwise, use persistence-oriented. The persistence-oriented style is more common in modern applications because it is more explicit. + +### Repository Implementation + +The repository interface lives in the domain layer. The implementation lives in the infrastructure layer. This is the Dependency Inversion Principle in action: + +``` +domain/ + model/ + Order.py # Aggregate root + OrderLineItem.py # Entity within aggregate + repository/ + OrderRepository.py # Interface (abstract class / protocol) + +infrastructure/ + persistence/ + PostgresOrderRepository.py # Implementation + InMemoryOrderRepository.py # Implementation for tests +``` + +The domain layer defines what it needs (the interface). The infrastructure layer provides it (the implementation). The domain never imports from infrastructure. + +### What a Repository Returns + +A repository always returns fully constituted aggregates -- not partial objects, not DTOs, not database rows. The aggregate returned from a repository must be in a valid state with all its invariants satisfied. + +**Correct:** `order_repository.find_by_id(id)` returns an `Order` with all its `OrderLineItems` loaded, ready to have business operations performed on it. + +**Incorrect:** `order_repository.find_by_id(id)` returns an `OrderDTO` with some fields populated and others lazily loaded. The caller must check which fields are available. + +### Repository Anti-Patterns + +| Anti-Pattern | Problem | Fix | +|-------------|---------|-----| +| Generic repository (`Repository`) | All aggregates look the same; domain-specific queries do not fit the generic interface | Create specific repository interfaces per aggregate type | +| Repository returns DTOs | DTOs are not domain objects; behavior cannot be called on them | Return full aggregates; use separate read models (CQRS) for queries | +| Repository per entity (not per aggregate) | Bypasses aggregate root; allows direct modification of internal entities | One repository per aggregate root only | +| Repository with business logic | Repository starts containing validation or transformation logic | Keep repositories as pure storage; domain logic belongs in the aggregate | +| Repository depends on domain services | Circular dependency between domain services and repositories | Repositories depend only on the domain model (aggregates, value objects) | + +## The Factory Pattern + +A Factory encapsulates the logic of creating a domain object, ensuring that the object is fully formed and valid from the moment it exists. In DDD, factories are used when object creation is complex enough to warrant its own abstraction. + +### When to Use a Factory + +| Situation | Factory Needed? | Why | +|-----------|----------------|-----| +| Creating a Value Object with 2-3 fields | No | A constructor suffices: `Money(100, "USD")` | +| Creating an aggregate with multiple parts and validation rules | Yes | The assembly logic is complex; a constructor would be enormous | +| Creating an object from an external representation (API response, file) | Yes | Translation from external format to domain object is a separate concern | +| Creating an object with conditional logic (different subtypes) | Yes | The decision of which subtype to create should not be in client code | +| Reconstituting an object from persistence | Maybe | If the repository handles it, a separate factory may not be needed | + +### Factory Patterns in DDD + +#### Factory Method on the Aggregate + +The most common pattern: a static or class method on the aggregate itself: + +``` +class Order: + @staticmethod + def create_from_cart(cart, customer_id): + # Validates cart is not empty + # Converts cart items to OrderLineItems + # Calculates initial total + # Returns a fully valid Order + order = Order( + id=OrderId.generate(), + customer_id=customer_id, + status=OrderStatus.PENDING, + items=[OrderLineItem.from_cart_item(item) for item in cart.items], + total=cart.calculate_total() + ) + order._raise_event(OrderCreated(...)) + return order +``` + +**Advantages:** Creation logic lives close to the aggregate. The aggregate controls its own birth. + +#### Factory Method on Another Aggregate + +When one aggregate creates another: + +``` +class Quote: + def convert_to_order(self): + # Quote knows how to create an Order from itself + order = Order( + id=OrderId.generate(), + customer_id=self.customer_id, + items=[OrderLineItem(item.product_id, item.quantity, item.quoted_price) + for item in self.line_items], + source_quote_id=self.id + ) + return order +``` + +#### Standalone Factory + +When creation logic does not naturally belong to any existing aggregate: + +``` +class LoanApplicationFactory: + def create_from_submission(self, submission, credit_report): + # Complex assembly involving multiple inputs + # Conditional logic based on loan type + # Validation against business rules + applicant = Applicant(submission.name, submission.ssn) + risk_score = RiskScore.calculate(credit_report) + + if submission.loan_type == "mortgage": + return MortgageApplication(applicant, risk_score, submission.property) + elif submission.loan_type == "auto": + return AutoLoanApplication(applicant, risk_score, submission.vehicle) +``` + +### Factory Invariants + +The most critical rule of factories: **a factory must never produce an invalid object.** If the inputs are insufficient or violate business rules, the factory must fail (throw an exception), not produce a partially valid object. + +``` +# Good -- factory enforces invariants +class Order: + @staticmethod + def create(customer_id, items): + if not items: + raise EmptyOrderError("Cannot create an order with no items") + if not customer_id: + raise InvalidCustomerError("Order requires a customer") + return Order(OrderId.generate(), customer_id, items) + +# Bad -- factory produces potentially invalid objects +class Order: + @staticmethod + def create(customer_id=None, items=None): + return Order(OrderId.generate(), customer_id, items or []) + # caller can now have an order with no customer and no items +``` + +### Reconstitution vs. Creation + +There is an important distinction between creating a new aggregate and reconstituting one from persistence: + +| Aspect | Creation | Reconstitution | +|--------|---------|----------------| +| When | A new domain object comes into existence | An existing object is loaded from storage | +| Validation | Full business rule validation | No validation needed; data was validated on creation | +| Domain events | May raise creation events (`OrderCreated`) | Should NOT raise events; nothing new happened | +| Identity | Generate a new ID | Use the stored ID | +| Invariants | Enforce all invariants | Assume invariants hold (data was valid when stored) | + +Reconstitution typically happens inside the repository implementation: + +``` +class PostgresOrderRepository: + def find_by_id(self, order_id): + row = self.db.query("SELECT * FROM orders WHERE id = ?", order_id) + items = self.db.query("SELECT * FROM order_items WHERE order_id = ?", order_id) + # Reconstitute -- no validation, no events + return Order._reconstitute( + id=row['id'], + customer_id=row['customer_id'], + status=row['status'], + items=[OrderLineItem._reconstitute(i) for i in items] + ) +``` + +## The Specification Pattern + +The Specification pattern encapsulates query criteria as first-class domain objects. Instead of building queries in service code, you express criteria as composable specification objects. + +### Why Specifications + +Without specifications, query logic scatters across the codebase: + +``` +# Query logic in a service -- not reusable, not composable +def find_risky_orders(self): + return db.query("SELECT * FROM orders WHERE total > 10000 AND customer_risk > 7") + +# Same logic duplicated elsewhere with slight variations +def find_very_risky_orders(self): + return db.query("SELECT * FROM orders WHERE total > 50000 AND customer_risk > 9") +``` + +With specifications: + +``` +high_value = OrderValueExceeds(10000) +high_risk = CustomerRiskAbove(7) +risky_orders = order_repository.find_matching(high_value.and_(high_risk)) + +very_risky = OrderValueExceeds(50000).and_(CustomerRiskAbove(9)) +very_risky_orders = order_repository.find_matching(very_risky) +``` + +### Specification Composition + +Specifications compose using logical operators: + +| Operator | Meaning | Example | +|----------|---------|---------| +| `and_` | Both must be true | `HighValue.and_(HighRisk)` | +| `or_` | Either must be true | `HighValue.or_(HighRisk)` | +| `not_` | Must not be true | `not_(Cancelled)` | + +### Specifications in the Domain Layer + +The specification interface lives in the domain layer. Implementations can be in the domain (for in-memory filtering) or infrastructure (for database queries): + +``` +# Domain layer -- specification interface +class Specification: + def is_satisfied_by(self, candidate) -> bool: + pass + +class OverdueInvoice(Specification): + def __init__(self, as_of_date): + self.as_of_date = as_of_date + + def is_satisfied_by(self, invoice): + return invoice.due_date < self.as_of_date and not invoice.is_paid +``` + +## Ports and Adapters Relationship + +Repositories and Factories fit naturally into the Ports and Adapters (Hexagonal) architecture: + +``` + Domain Layer + ┌─────────────────────────┐ + │ Aggregates │ + │ Value Objects │ + │ Domain Events │ + │ Repository Interfaces ──┼── Port (interface) + │ Factory Interfaces ──┼── Port (interface) + └─────────────────────────┘ + │ + │ implements + ▼ + Infrastructure Layer + ┌─────────────────────────┐ + │ PostgresOrderRepo ──┼── Adapter (implementation) + │ InMemoryOrderRepo ──┼── Adapter (for tests) + │ S3DocumentFactory ──┼── Adapter (implementation) + └─────────────────────────┘ +``` + +**The key principle:** The domain defines what it needs (ports). Infrastructure provides it (adapters). Dependencies point inward -- infrastructure depends on domain, never the reverse. + +This means: +- The domain layer has zero imports from infrastructure packages +- Repository interfaces use domain types (`Order`, `OrderId`), not infrastructure types (`Row`, `Document`) +- The application can swap persistence technologies by providing a new adapter without touching domain code +- Tests use in-memory adapters to test domain logic without databases diff --git a/.agents/skills/domain-driven-design/references/strategic-design.md b/.agents/skills/domain-driven-design/references/strategic-design.md new file mode 100644 index 00000000..a27bfe44 --- /dev/null +++ b/.agents/skills/domain-driven-design/references/strategic-design.md @@ -0,0 +1,251 @@ +# Strategic Design and Distillation + +Strategic design is the practice of identifying which parts of a system matter most and allocating design effort accordingly. Not all code is created equal. Some code is the reason the business exists; other code is necessary plumbing. Domain distillation is the process of separating the essential from the incidental, so that the core of the domain model receives the deepest thought and the best talent. + +## The Three Types of Subdomains + +Eric Evans classifies every part of a system into one of three subdomain types. This classification drives every major design and investment decision. + +### Core Domain + +The Core Domain is the part of the system that provides competitive advantage. It is the reason the business exists and what differentiates it from competitors. Without it, the business has no unique value proposition. + +**Characteristics:** +- Contains the most complex and nuanced business rules +- Is the source of competitive advantage +- Changes frequently as the business evolves its strategy +- Cannot be outsourced without losing differentiation +- Requires the deepest domain expertise + +**Examples:** + +| Business | Core Domain | Why It Is Core | +|----------|-------------|----------------| +| Amazon | Recommendation engine, marketplace matching, logistics optimization | These are the algorithms that make Amazon uniquely effective | +| Stripe | Payment processing, fraud detection, developer experience | These are what make Stripe better than alternatives | +| Netflix | Content recommendation, streaming optimization | These keep subscribers engaged and differentiators from competitors | +| Insurance company | Risk assessment, claims adjudication, actuarial modeling | These determine profitability and pricing accuracy | +| Trading firm | Signal generation, execution algorithms, risk management | These are the source of alpha | + +**Investment rule:** Put your best developers here. Apply the deepest modeling techniques. This is where DDD patterns earn their complexity cost. + +### Supporting Subdomain + +A Supporting Subdomain is necessary for the business to function but does not provide competitive advantage. It supports the Core Domain. You build it because off-the-shelf solutions do not fit your specific needs, but you do not need to over-engineer it. + +**Characteristics:** +- Custom-built because available solutions do not quite fit +- Important but not differentiating +- Moderately complex; business-specific but not competitively critical +- Can be built by competent developers without deep domain modeling + +**Examples:** + +| Business | Supporting Subdomain | Why It Is Supporting | +|----------|---------------------|---------------------| +| E-commerce platform | Order management, inventory tracking | Necessary for operations but not what makes this e-commerce site unique | +| Insurance company | Policy administration, document generation | Must work correctly but is not a competitive differentiator | +| Trading firm | Position reporting, compliance reporting | Regulatory requirement, not a source of trading advantage | +| SaaS product | Tenant management, billing integration | Needed but not what customers buy the product for | + +**Investment rule:** Build it, but keep it simple. Use straightforward designs. Do not apply deep DDD modeling patterns unless the complexity warrants it. + +### Generic Subdomain + +A Generic Subdomain is functionality that is common across many businesses and has no business specificity. It is commodity software that you should buy, use open-source, or outsource. + +**Characteristics:** +- Not specific to your business; every company needs it +- Well-solved problems with mature solutions available +- Building it yourself is a waste of your best developers' time +- Off-the-shelf solutions are often better than what you would build + +**Examples:** + +| Generic Subdomain | Buy/Use Instead | +|-------------------|----------------| +| Authentication and authorization | Auth0, Okta, Keycloak, Clerk | +| Email sending | SendGrid, Amazon SES, Postmark | +| Payment processing (if not your core) | Stripe, Braintree, Adyen | +| File storage | Amazon S3, Google Cloud Storage | +| Search indexing | Elasticsearch, Algolia, Typesense | +| Monitoring and alerting | Datadog, Grafana, PagerDuty | +| CMS / Content management | WordPress, Contentful, Sanity | + +**Investment rule:** Do not build this. Buy it, use open-source, or outsource it. Every hour your best developer spends building a custom email sender is an hour stolen from the Core Domain. + +## Identifying Your Core Domain + +### The Differentiation Test + +For each part of the system, ask: "If a competitor had exactly the same implementation of this, would we lose our competitive advantage?" + +- **Yes, we would lose advantage:** Core Domain +- **No, but we would be inconvenienced:** Supporting Subdomain +- **No, and we could swap it easily:** Generic Subdomain + +### The Outsourcing Test + +Ask: "Could we outsource this to a competent contractor or replace it with a SaaS product without damaging our competitive position?" + +- **No, absolutely not -- this is our secret sauce:** Core Domain +- **Maybe, but it would need customization:** Supporting Subdomain +- **Yes, easily:** Generic Subdomain + +### The Talent Test + +Ask: "Does working on this require deep expertise in our specific business domain?" + +- **Yes -- only people who deeply understand our industry can get this right:** Core Domain +- **Somewhat -- general software skills with some domain knowledge:** Supporting Subdomain +- **No -- any competent developer could implement this:** Generic Subdomain + +### Common Misclassification Errors + +| Error | Reality | Consequence | +|-------|---------|-------------| +| "Everything is core" | Most things are supporting or generic | Best talent spread thin; nothing gets deep modeling | +| "Our custom CRM is core" | CRM is generic; your customer relationships are core | Team spent years building what Salesforce does better | +| "Authentication is core" | Authentication is generic (unless you are Auth0) | Security expertise wasted on commodity functionality | +| "Infrastructure is core" | Infrastructure is generic (unless you are AWS) | Platform team grows while product team starves | +| "Our billing system is core" | Billing is usually supporting or generic | Over-engineered billing while the actual product suffered | + +## Domain Distillation + +Distillation is the process of extracting and clarifying the Core Domain from the rest of the system. It makes the most important parts of the model explicit, visible, and well-understood. + +### The Domain Vision Statement + +A Domain Vision Statement is a short document (one page or less) that describes the Core Domain's value proposition and its most important aspects. It serves as a north star for the team. + +**What it contains:** +- What makes this domain unique and valuable +- What distinguishes the Core Domain from everything else in the system +- What the domain model must capture to deliver competitive advantage +- What the team should focus on and what they should explicitly not focus on + +**Example for an insurance company:** + +> Our competitive advantage is our ability to accurately assess risk in real-time for commercial property insurance. Our core domain model must capture the nuanced relationships between property characteristics, geographic risk factors, historical claims data, and market conditions. The model must support rapid repricing as conditions change. Everything else -- policy administration, document generation, payment processing -- is supporting infrastructure that must work correctly but does not differentiate us. + +### The Highlighted Core + +The Highlighted Core is a technique for making the Core Domain visually obvious in the codebase and in documentation. + +**In documentation:** +- Create a document that marks which modules, classes, and interactions constitute the Core Domain +- Use diagrams that distinguish core from supporting from generic +- Keep this document updated as the model evolves + +**In code:** +- Organize the codebase so that Core Domain modules are clearly separated: `domain/core/`, `domain/supporting/`, `infrastructure/` +- Use naming conventions that signal importance: a module called `pricing-engine` conveys more importance than `util-helpers` +- Code review standards can be higher for core domain code (require domain expert sign-off) + +### Distillation Techniques + +#### Segregated Core + +Physically separate the Core Domain from the rest of the codebase. The core should have no dependencies on supporting or generic subdomains -- only the other way around. + +``` +src/ + core/ # Core Domain -- deepest modeling + risk-assessment/ + RiskModel.py + RiskFactor.py + UnderwritingRules.py + pricing/ + PricingEngine.py + RateTable.py + supporting/ # Supporting -- necessary, simpler design + policy-admin/ + PolicyRepository.py + PolicyDocument.py + notifications/ + NotificationService.py + generic/ # Generic -- thin wrappers around external services + email/ + EmailGateway.py + storage/ + FileStorage.py + auth/ + AuthenticationAdapter.py +``` + +#### Abstract Core + +Create a distilled model that captures the essential abstractions of the Core Domain without the implementation details. This abstract model serves as a communication tool and a guide for detailed implementation. + +The Abstract Core is like an executive summary of the domain model: it captures the key concepts, their relationships, and the most important business rules, without the full detail of every attribute and method. + +## Build vs. Buy vs. Outsource + +### Decision Framework + +| Question | Core Domain | Supporting Subdomain | Generic Subdomain | +|----------|-------------|---------------------|-------------------| +| Should we build it in-house? | **Yes, always** | Yes, if no good fit exists | **No** | +| Should we buy/use SaaS? | **No** -- too important to delegate | Only if it fits well | **Yes, always** | +| Should we outsource development? | **No** -- requires deep domain expertise | Possible with good specs | **Yes** -- or better yet, buy | +| Should we use open-source? | Only as a foundation to build on | Yes, if it fits | **Yes** | +| What quality standard? | Highest -- deep modeling, extensive testing, expert review | Good -- solid engineering, adequate testing | Adequate -- it just needs to work | + +### The Opportunity Cost Lens + +Every hour spent on non-core work is an hour not spent on the Core Domain. Frame build-vs-buy decisions as opportunity costs: + +- "We could build our own email service in 3 months." That is 3 months your best developers are not improving the Core Domain. Use SendGrid. +- "We could build a custom monitoring dashboard in 6 weeks." That is 6 weeks not spent on the pricing engine. Use Grafana. +- "We could build our own authentication system in 2 months." That is 2 months of security engineering not applied to fraud detection. Use Auth0. + +### When "Buy" Becomes "Core" + +Sometimes a generic subdomain becomes core as the business evolves: + +- Stripe started as a payment processor (generic for most businesses) but made payments their Core Domain +- Amazon started as a bookstore; logistics (supporting for most retailers) became a Core Domain that turned into AWS +- Netflix treated content recommendation as core from the beginning, while most video platforms treated it as supporting + +**Revisit classifications regularly.** What is generic today may become core tomorrow if the business strategy shifts. Annual or quarterly reviews of subdomain classifications prevent stale assumptions. + +## Applying Strategic Design to Team Structure + +### Team Allocation by Subdomain Type + +| Subdomain Type | Team Characteristics | Practices | +|---------------|---------------------|-----------| +| Core Domain | Senior engineers, domain experts embedded in team, smallest and most skilled team | Deep modeling, event storming, pair programming with domain experts, extensive testing | +| Supporting Subdomain | Mid-level engineers, domain knowledge acquired through documentation | Standard engineering practices, adequate testing, clear interfaces | +| Generic Subdomain | Junior engineers or no team at all (use external service) | Integration work, adapter implementation, vendor management | + +### Conway's Law Application + +Design team boundaries to match desired bounded context boundaries: + +- One team per bounded context (or small number of contexts) +- Core Domain teams should be co-located or closely collaborating +- Supporting Subdomain teams can be more independent +- Generic Subdomain work can be distributed or handled by a platform team + +### Investment Over Time + +As the system matures, investment should shift: + +| Phase | Core Domain Investment | Supporting Investment | Generic Investment | +|-------|----------------------|----------------------|-------------------| +| Early (MVP) | 70% | 20% | 10% (buy everything) | +| Growth | 60% | 25% | 15% (integrate more) | +| Mature | 50% | 30% | 20% (optimize and replace) | + +The Core Domain always receives the plurality of investment. If it drops below 50%, the team is likely over-engineering supporting functionality or building generic functionality that should be bought. + +## Strategic Design Anti-Patterns + +| Anti-Pattern | Signal | Fix | +|-------------|--------|-----| +| "Golden hammer" -- applying Core Domain rigor to everything | Every module has aggregates, repositories, domain events, factories | Classify subdomains; simplify supporting and generic code | +| "Platform first" -- building infrastructure before product | Months spent on logging, monitoring, and deployment before a single domain feature | Use off-the-shelf infrastructure; build Core Domain features first | +| "Resume-driven development" -- choosing technology for novelty | Core Domain uses experimental framework because it is interesting | Choose boring technology for production; innovate in modeling, not infrastructure | +| "Outsourced core" -- contracting out the competitive advantage | Core Domain built by offshore team with no domain expertise | Bring core development in-house; invest in domain expert access | +| "Everyone is equal" -- same standards and investment everywhere | No distinction between a pricing algorithm and a CRUD admin panel | Apply deep modeling only where it pays off; keep the rest simple | diff --git a/.agents/skills/domain-driven-design/references/ubiquitous-language.md b/.agents/skills/domain-driven-design/references/ubiquitous-language.md new file mode 100644 index 00000000..c9377199 --- /dev/null +++ b/.agents/skills/domain-driven-design/references/ubiquitous-language.md @@ -0,0 +1,202 @@ +# Ubiquitous Language + +The single most important practice in Domain-Driven Design. A ubiquitous language is the shared vocabulary between developers and domain experts that is used everywhere -- in conversation, documentation, code, tests, and diagrams. It is not a glossary appended to a wiki. It is the living, evolving language that shapes how the system is built and how the team thinks about the domain. + +## Why Language Matters More Than Code + +Software development is fundamentally a communication problem. The hardest bugs are not off-by-one errors or null pointer exceptions -- they are misunderstandings between people. When a developer hears "account" and thinks "user login record" while the domain expert means "financial ledger position," the resulting code will be structurally wrong in ways that no amount of testing can catch. + +A ubiquitous language eliminates this class of failure by establishing a single, precise vocabulary that both sides use without translation. When the language is embedded in code, every class name, method name, and variable name becomes a checkpoint: if a domain expert cannot read the code and recognize the concepts, the model is wrong. + +### The Cost of Translation + +Without a ubiquitous language, every conversation requires mental translation: + +| Developer Says | Domain Expert Hears | Actual Meaning | Risk | +|---------------|--------------------|-|------| +| `UserEntity` | "User? We don't have users, we have policyholders" | The system models a concept the business does not recognize | Code does not reflect reality; edge cases are missed | +| `processData()` | "Process what data? Which business operation?" | A generic method hiding domain-specific logic | Business rules buried in implementation; impossible to validate | +| `status = 3` | "What does 3 mean?" | An opaque encoding of a domain concept | Magic numbers replace meaningful domain states | +| `ServiceManager` | "Manager of what?" | A catch-all class with no domain analog | God class accumulates unrelated responsibilities | + +### The Payoff of Alignment + +When the language is shared: + +- **Domain experts can read tests.** A test that says `policy.underwrite(application)` is immediately meaningful. A test that says `service.process(dto)` is opaque. +- **Developers catch domain errors.** When a developer writes `order.cancel()` and the domain expert says "we don't cancel orders, we void them," the naming mismatch reveals a modeling error. +- **New team members onboard faster.** The codebase teaches the domain because the names are the domain. +- **Refactoring is safer.** Renaming `process()` to `adjudicateClaim()` is not just cosmetic -- it encodes domain knowledge that prevents future misuse. + +## Building the Language + +### Start with Domain Expert Conversations + +The language does not come from developers reading documentation. It comes from intensive, iterative conversations between developers and domain experts. These conversations follow a pattern: + +1. **Listen for the nouns and verbs the expert uses naturally.** "When a claim comes in, the adjuster reviews it, and then we either approve or deny the claim." The nouns are `Claim`, `Adjuster`. The verbs are `review`, `approve`, `deny`. + +2. **Challenge ambiguity.** "You said 'review' -- what exactly happens during a review? Is it the same as 'assess'?" Often the expert will distinguish between terms that outsiders conflate. + +3. **Propose the model.** "So a `Claim` goes through an `Adjudication` process where an `Adjuster` either `approves` or `denies` it?" The expert corrects: "Not exactly -- the adjuster makes a recommendation, but only a senior adjuster can approve claims over $10,000." + +4. **Refine until the model is precise.** The conversation reveals business rules that no requirements document captured: approval authority limits, recommendation vs. decision, escalation paths. + +### Model Exploration Whirlpool + +Eric Evans describes a "whirlpool" process for modeling: + +1. **Scenario walkthrough.** Walk through concrete business scenarios with domain experts. "A customer calls to report damage to their vehicle. What happens next?" + +2. **Concept extraction.** Identify the key domain concepts that emerge: `Claim`, `Incident`, `CoverageVerification`, `DamageAssessment`. + +3. **Name negotiation.** Debate and agree on names. "Should we call it a 'damage report' or a 'claim'? When does a report become a claim?" + +4. **Code spike.** Quickly implement the emerging model in code to test whether it holds up under real logic. + +5. **Feedback loop.** Show the code (or at least the class and method names) back to the domain expert. "Does this look right to you?" + +This cycle repeats continuously throughout the project, not just at the beginning. + +## Language in Code + +### Naming Classes After Domain Concepts + +Every class in the domain layer should be named after a concept the business recognizes: + +**Good names (domain language):** +- `LoanApplication` -- the business knows what this is +- `CreditDecision` -- an explicit outcome of an underwriting process +- `PaymentSchedule` -- a concrete domain concept +- `PolicyRenewalNotice` -- named exactly as the business document is named + +**Bad names (technical language):** +- `ApplicationDTO` -- DTO is a technical pattern, not a domain concept +- `PaymentService` -- "service" is a technical role, not a domain concept; what does this service do? +- `DataProcessor` -- meaningless in domain terms +- `BaseEntityAbstractFactory` -- pure technical jargon + +### Naming Methods After Domain Operations + +Methods should read like sentences a domain expert would say: + +**Good:** +``` +policy.renew(effectiveDate) +claim.submitForAdjudication() +account.applyInterest(rate, period) +order.fulfillWith(shipment) +``` + +**Bad:** +``` +policy.update(data) +claim.process() +account.calculate() +order.setStatus(STATUS_SHIPPED) +``` + +The difference is not cosmetic. `claim.submitForAdjudication()` tells you what the business operation is. `claim.process()` tells you nothing -- you must read the implementation to understand what it does, which means the domain knowledge is hidden. + +### Naming Events After Domain Facts + +Domain events should be named as past-tense facts that a domain expert would recognize as significant business occurrences: + +**Good:** `PolicyIssued`, `ClaimDenied`, `PaymentOverdue`, `MembershipExpired` + +**Bad:** `PolicyUpdated`, `ClaimProcessed`, `DataChanged`, `RecordModified` + +"Updated," "processed," and "changed" are technical descriptions of what happened to data. "Issued," "denied," "overdue," and "expired" are domain descriptions of what happened in the business. + +## Glossary Maintenance + +### The Living Glossary + +Maintain a glossary document that evolves with the model. This is not a static artifact created at the start of the project and forgotten. It is a living document updated every time the language changes. + +**What goes in the glossary:** + +| Term | Definition | Context | Example | +|------|-----------|---------|---------| +| Claim | A formal request for payment under an insurance policy following a covered event | Claims processing | "The policyholder filed a claim for water damage" | +| Adjudication | The process of evaluating a claim to determine whether it is covered and how much to pay | Claims processing | "The claim is in adjudication pending the damage assessment" | +| Coverage | The set of perils and limits defined in a policy | Underwriting | "This policy provides coverage for fire but not flood" | +| Premium | The amount the policyholder pays for coverage | Billing | "The annual premium is $1,200, payable monthly" | + +**What does NOT go in the glossary:** +- Technical terms (`Repository`, `Service`, `Controller`) +- Implementation details (`PostgreSQL table name`, `API endpoint`) +- Generic programming concepts (`interface`, `abstract class`) + +### When Terms Conflict + +The same word often means different things in different parts of the business. This is expected and healthy: + +- **"Account"** in billing means a financial ledger position. In authentication, it means a user login. In sales, it means a company relationship. +- **"Product"** in the catalog means something you can browse. In inventory, it means a physical item with a location. In marketing, it means a brand offering. + +The solution is not to force one definition. The solution is bounded contexts: each context has its own definition, and translations happen at the boundary. + +## Language Evolution + +### When to Change the Language + +The ubiquitous language is not fixed. It evolves as the team's understanding of the domain deepens. Signals that the language needs to change: + +- **Awkward conversations.** "Well, it's kind of like a customer but not exactly -- it's more of an applicant who might become a customer." This means `Customer` is the wrong term; `Applicant` is a distinct concept. +- **Workarounds in code.** A `type` field that switches behavior (e.g., `if customer.type == 'prospect'`) often means a single class is trying to represent two different domain concepts. +- **Expert correction.** "We don't really call it a 'request' -- we call it a 'submission.'" Change the code immediately. +- **New domain insight.** "Actually, a cancellation and a voiding are different things. Cancellation is prospective; voiding is retroactive." Split the concept. + +### The Refactoring Trigger + +When the language changes, the code must change. This is not optional. If the team agrees that "submission" is the correct term instead of "request," then: + +1. Rename the class: `Request` becomes `Submission` +2. Rename the repository: `RequestRepository` becomes `SubmissionRepository` +3. Rename the events: `RequestCreated` becomes `SubmissionFiled` +4. Update the database: table `requests` becomes `submissions` (with a migration) +5. Update the API: `/api/requests` becomes `/api/submissions` (with versioning) + +This may seem expensive, but the cost of maintaining a divergence between language and code is far higher. Every time a developer reads `Request` and has to mentally translate to "submission," they lose context and risk introducing errors. + +## How Naming Shapes Design + +Names are not labels applied after the fact. They are design decisions that constrain and guide the system's evolution. + +### Names Reveal Missing Concepts + +When you struggle to name something, the model is telling you something is wrong: + +- **"OrderProcessorHelper"** -- If you need a helper, the class it is helping probably has the wrong boundaries. The behavior likely belongs inside `Order` or in a separate, well-named domain concept. +- **"MiscService"** -- If you cannot name it, you do not understand it. Break it apart until each piece has a clear domain name. +- **"DataValidator"** -- Validation of what? By what rules? `CreditApplicationValidator` or `AddressVerifier` tells you exactly what domain rules are being enforced. + +### Names Prevent Misuse + +A method named `account.debit(amount)` tells future developers exactly what this does and constrains its usage. A method named `account.update(amount)` invites misuse because "update" could mean anything. + +### Names Create Boundaries + +When two concepts share a name but have different behaviors, splitting the name splits the model: + +- `Customer` in sales vs. `Customer` in billing? These are different bounded contexts. The split in naming reveals the split in models. +- `Order` before payment vs. `Order` after payment? Perhaps these are `PendingOrder` and `ConfirmedOrder` -- two distinct states that deserve distinct types, not a `status` flag. + +## Anti-Patterns to Avoid + +### The Jargon Trap + +Developers invent internal jargon that has no domain analog: "We call it a 'widget' internally." If domain experts do not use the word "widget," it does not belong in the domain model. + +### The Abbreviation Trap + +`CustAcctMgr` is not a ubiquitous language term. Write `CustomerAccountManager` -- or better yet, ask what the business actually calls this role. Maybe it is a `RelationshipOfficer` or an `AccountExecutive`. + +### The Thesaurus Trap + +Using synonyms interchangeably (`customer` / `client` / `user` / `patron`) destroys precision. Pick one term per concept and enforce it everywhere. If the business uses "client" in legal contexts and "customer" in sales contexts, those are different bounded contexts with different terms -- and both are correct within their context. + +### The Persistence Trap + +Naming domain concepts after their storage mechanism: `CustomerRecord`, `OrderRow`, `PaymentTable`. Domain objects are not records or rows. They are domain concepts that happen to be persisted. Name them for what they are in the domain: `Customer`, `Order`, `Payment`. diff --git a/.agents/skills/drive-motivation/SKILL.md b/.agents/skills/drive-motivation/SKILL.md new file mode 100644 index 00000000..b8fbc582 --- /dev/null +++ b/.agents/skills/drive-motivation/SKILL.md @@ -0,0 +1,200 @@ +--- +name: drive-motivation +description: 'Design motivation systems using Autonomy, Mastery, and Purpose (AMP) for products and teams. Use when the user mentions "intrinsic motivation", "gamification isnt working", "rewards arent working", "autonomy", "mastery", "purpose-driven", "my team is disengaged", or "how do I motivate people". Also trigger when designing onboarding progression, fixing broken gamification, or building team structures that sustain high performance. Covers why carrot-and-stick fails and how to build progress systems. For habit-forming product loops, see hooked-ux. For retention behavior design, see improve-retention.' +license: MIT +metadata: + author: wondelai + version: "1.4.0" +--- + +# Drive Motivation Framework + +Design motivation systems for products, teams, and organizations using the science of intrinsic motivation. + +## Core Principle + +**The secret to high performance isn't rewards and punishment — it's the deeply human need to direct our own lives, learn and create new things, and do better for ourselves and our world.** For any task requiring even rudimentary cognitive effort, external rewards either don't work or actively worsen performance. Intrinsic motivation — Autonomy, Mastery, Purpose (AMP) — drives lasting engagement. + +## Scoring + +**Goal: 10/10.** Score any motivation system (product features, team incentives, gamification, engagement loops) against the [Quick Diagnostic](#quick-diagnostic): start at 5, add 1 for each of the first five rows answered "yes," then **subtract 2 if the sixth row is also "yes"** — an "if-then" reward doing the motivating crowds out the rest. Bands: + +- **9-10** — autonomy, mastery, and purpose all present; no if-then crowding-out. +- **5-6** — one pillar carries the system; the other two are weak or extrinsic. +- **≤3** — relies on rewards, mandates, or controlling behaviors; intrinsic motivation absent. + +Always state the current score, which diagnostic rows failed, and the specific fixes to reach 10/10. + +## Motivation 1.0, 2.0, and 3.0 + +| Version | Core Assumption | Approach | Era | +|---------|----------------|----------|-----| +| **1.0** | Humans are biological | Survival drives | Pre-industrial | +| **2.0** | Humans respond to rewards/punishments | Carrot and stick | Industrial age | +| **3.0** | Humans seek autonomy, mastery, purpose | Intrinsic motivation | Knowledge economy | + +### The Seven Deadly Flaws of Extrinsic Rewards + +"If-then" rewards ("If you do X, then you get Y"): + +| Flaw | Mechanism | Example | +|------|-----------|---------| +| **1. Extinguish intrinsic motivation** | Turns play into work | Kids paid to draw stopped drawing when payments stopped | +| **2. Diminish performance** | Narrow focus, reduce creativity | Candle problem: rewarded group performed worse | +| **3. Crush creativity** | Reward focus replaces exploration | Commissioned art rated less creative | +| **4. Crowd out good behavior** | Financial framing replaces moral framing | Day-care late fee: lateness increased (became a "service") | +| **5. Encourage cheating** | Goal fixation invites shortcuts | Wells Fargo fake accounts | +| **6. Become addictive** | Bigger rewards needed over time | Last year's bonus = this year's expectation | +| **7. Foster short-term thinking** | Optimize for the reward period | Quarterly bonuses → quarterly thinking | + +**The boundary:** extrinsic rewards work only for routine, algorithmic tasks with no intrinsic interest. For creative work, complex problem-solving, or long-term engagement, they backfire. + +See [references/extrinsic-rewards.md](references/extrinsic-rewards.md) when a reward or incentive scheme is backfiring — the named studies behind each flaw and a decision rule for when rewards are safe to use. + +## The Three Pillars: Autonomy, Mastery, Purpose + +### 1. Autonomy + +**Core concept:** The desire to direct our own lives — choice over what, when, how, and with whom. Autonomy ≠ independence: people can act with choice while staying interdependent with a team. + +**The Four T's of Autonomy:** + +| Dimension | Question | Example | +|-----------|----------|---------| +| **Task** | What do I work on? | Google's 20% time, Atlassian ShipIt days | +| **Time** | When do I work? | Flexible hours, no mandatory meetings | +| **Technique** | How do I do it? | Choose tools, methods, approach | +| **Team** | Who do I work with? | Self-forming teams | + +**Product applications:** + +| Context | Autonomy Killer | Autonomy Enabler | +|---------|----------------|-------------------| +| **Onboarding** | Forced linear tutorial | Choose your path, skip steps | +| **Content** | Algorithm-only feed | User-controlled feeds, filters | +| **Workflow** | Rigid process, feature bloat | Custom automations, show/hide, progressive disclosure | + +**Autonomy violations:** "You must complete X before Y", unskippable tutorials, mandatory notifications, and forced single paths through the experience. + +See [references/autonomy.md](references/autonomy.md) when designing onboarding, feeds, or workflow controls — full Four T's patterns plus the autonomy audit checklist. + +### 2. Mastery + +**Core concept:** The desire to get better at something that matters. Mastery is a mindset, not a destination — it's asymptotic, and the joy is in the pursuit. + +**Three laws of mastery:** + +- **Mastery is a mindset** — ability is developed, not fixed (Dweck's growth mindset). Frame failures as learning, not judgment. +- **Mastery is a pain** — it demands effort and deliberate practice. Flow (Csikszentmihalyi) lives between boredom and anxiety, so calibrate challenge to skill level. +- **Mastery is asymptotic** — users never fully arrive. Always offer a next level, next challenge. + +**Flow conditions:** clear goals, immediate feedback, challenge/skill balance, sense of control. + +**Product applications:** + +| Context | Mastery Design | Example | +|---------|---------------|---------| +| **Progress** | Visible skill development | GitHub contribution graph, Duolingo levels | +| **Difficulty** | Adaptive challenge | Games that adjust to player skill | +| **Feedback** | Immediate, clear signals | Grammarly real-time writing analysis | + +**Mastery violations:** flat difficulty that never adapts, and failure that is punished rather than framed as learning. + +See [references/mastery.md](references/mastery.md) when designing progress, difficulty, or feedback systems — flow-state calibration, deliberate practice, and the mastery audit checklist. + +### 3. Purpose + +**Core concept:** The yearning to act in service of something larger than ourselves. Purpose is the context for the other two pillars — without it, autonomy is directionless and mastery hollow. + +**Three expressions of purpose:** + +| Expression | How It Manifests | Example | +|-----------|-----------------|---------| +| **Goals** | Purpose-driven objectives | TOMS: every purchase helps a person in need | +| **Words** | Language of purpose, not profit | "Associates" not "employees", "community" not "users" | +| **Policies** | Actions that demonstrate purpose | Patagonia: "Don't Buy This Jacket" | + +**Product applications:** + +| Context | Purpose Design | Example | +|---------|---------------|---------| +| **Impact** | Show the user's contribution | Wikipedia edit counter, Kiva lending impact | +| **Community** | Connect to something bigger | Open source contributions, community goals | +| **Values** | Align product with beliefs | Ecosia: "Search the web to plant trees" | + +**Purpose prescriptions:** show aggregate impact ("Together, our users have saved 1M hours"), connect individual actions to collective outcomes, and celebrate meaningful milestones over vanity metrics. + +See [references/purpose.md](references/purpose.md) when wiring impact, community, or values features — Goals/Words/Policies patterns and the purpose audit checklist. + +## AMP Applied: Product Design + +### Gamification Done Right vs. Wrong + +| Principle | Bad (Extrinsic) | Good (Intrinsic) | +|-----------|-----------------|-------------------| +| **Autonomy** | Forced challenges, mandatory participation | Opt-in, chosen challenges | +| **Mastery** | Points for everything, trivial badges | Skill-based progression, meaningful milestones | +| **Purpose** | Pointless competition, discouraging leaderboards | Community contribution, personal growth | + +**Example — Duolingo:** autonomy (choose language, pace, topics), mastery (adaptive difficulty, skill levels), purpose ("learn a language to connect with people"). Caution: streaks can shift from intrinsic mastery to extrinsic loss aversion. + +### Team Motivation + +| Principle | Manager Action | Example | +|-----------|---------------|---------| +| **Autonomy** | Hand over task, time, technique, team | "Here's the goal. How you get there is up to you." | +| **Mastery** | Provide challenge, feedback, growth | Stretch assignments, mentorship, learning budget | +| **Purpose** | Connect work to mission | "Here's why this matters for our customers" | + +### Compensation and Incentives + +Pay people enough to take money off the table — fair, ideally above-market — then focus on AMP; beyond "enough," more money doesn't increase motivation. Prefer "now-that" rewards (unexpected recognition after the fact: "You hit target! Here's a bonus.") over "if-then" rewards ("If you hit target, you get a bonus"), which create pressure and short-term thinking. + +See [references/applications.md](references/applications.md) when applying AMP to a concrete gamification, team-management, or compensation design — worked examples and escalation tables. + +## Type I vs. Type X Behavior + +| Type X (Extrinsic) | Type I (Intrinsic) | +|--------------------|---------------------| +| Fueled by external rewards | Fueled by autonomy, mastery, purpose | +| Seeks external recognition | Seeks inherent satisfaction | +| Short-term focus, fixed mindset | Long-term focus, growth mindset | + +Design products and teams that cultivate Type I behavior: it's made, not born; it doesn't disdain money or recognition; it's renewable; and it promotes well-being. + +See [references/type-i.md](references/type-i.md) when shifting a team or user base from Type X to Type I — the full behavioral contrast and conversion tactics. For real-world AMP programs (Atlassian ShipIt, 3M, ROWE, Duolingo, Wikipedia), see [references/case-studies.md](references/case-studies.md). + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|------| +| **Points for everything** | Crowds out intrinsic motivation | Reserve rewards for meaningful milestones | +| **Mandatory participation** | Kills autonomy | Make engagement opt-in | +| **Same challenge for everyone** | No flow — boredom or anxiety | Adaptive difficulty matching | +| **No visible progress** | Mastery is invisible | Progress indicators, skill tracking | +| **Missing "why"** | Actions feel meaningless | Connect every feature to purpose | +| **If-then bonuses** | Short-term thinking, gaming | Pay fairly; use "now-that" rewards; focus on AMP | + +## Quick Diagnostic + +Audit any motivation system: + +| Question | If No | Action | +|----------|-------|--------| +| Can users choose what/when/how? | Autonomy violation | Add choices, flexibility, customization | +| Can users see their progress? | No mastery signal | Add progress tracking, skill levels | +| Is challenge matched to skill? | Boredom or anxiety | Implement adaptive difficulty | +| Is there immediate feedback? | Can't improve | Add real-time response to actions | +| Does the user know WHY this matters? | No purpose | Connect to mission, show impact | +| Are we using "if-then" rewards? | Extrinsic crowding-out | Switch to "now-that" or intrinsic design | + +## Further Reading + +Based on Daniel Pink's research on motivation science: + +- [*"Drive: The Surprising Truth About What Motivates Us"*](https://www.amazon.com/Drive-Surprising-Truth-About-Motivates/dp/1594484805?tag=wondelai00-20) by Daniel H. Pink +- [*"To Sell Is Human"*](https://www.amazon.com/Sell-Human-Surprising-Moving-Others/dp/1594631905?tag=wondelai00-20) by Daniel H. Pink (applying motivation to sales and persuasion) + +## About the Author + +**Daniel H. Pink** is the author of seven books, including four New York Times bestsellers. *Drive*, translated into 40+ languages, changed how organizations think about motivation, and his TED Talk on motivation science is among the most-viewed of all time. He was previously chief speechwriter for Vice President Al Gore. diff --git a/.agents/skills/drive-motivation/references/applications.md b/.agents/skills/drive-motivation/references/applications.md new file mode 100644 index 00000000..0b5851d7 --- /dev/null +++ b/.agents/skills/drive-motivation/references/applications.md @@ -0,0 +1,274 @@ +# AMP Applied: Practical Applications of Autonomy, Mastery, and Purpose + +This reference translates the AMP framework from theory into practice across six domains: product gamification, team management, onboarding, education, health/fitness, and productivity tools. Each section includes specific design patterns, transformation examples, and implementation checklists. + +## AMP Applied to Product Design and Gamification + +### Wrong Gamification (Motivation 2.0) + +Most gamification implementations fail because they bolt extrinsic reward mechanics onto products without addressing intrinsic motivation. This is "chocolate-covered broccoli" -- the wrapper doesn't change the experience. + +| Extrinsic Mechanic | Why It Fails | What Users Actually Feel | +|--------------------|-------------|-------------------------| +| Points for every action | Devalues meaningful achievement | "These points are meaningless" | +| Badges for trivial tasks | No connection to real skill | "I got a badge for clicking a button" | +| Global leaderboards | 99% of users can never compete | "I'll never catch up, why try" | +| Daily login rewards | Trains habit without value | "I'm only here for the reward" | +| Time-limited challenges | Creates anxiety, not engagement | "I'm stressed, not motivated" | +| Social pressure mechanics | Guilt-driven, not interest-driven | "Stop telling me my friends are ahead" | + +### Right Gamification (Motivation 3.0) + +Intrinsic gamification designs for autonomy, mastery, and purpose -- the game mechanics serve the user's growth, not the product's metrics. + +| AMP Principle | Design Pattern | Example | +|---------------|---------------|---------| +| **Autonomy** | Choose your own challenges | Habitica: pick which habits to track | +| **Autonomy** | Multiple paths to goals | Duolingo: choose topic order | +| **Autonomy** | Opt-in competitions | Strava: join challenges voluntarily | +| **Mastery** | Skill-based progression | Codecademy: unlock harder problems as skills grow | +| **Mastery** | Adaptive difficulty | Chess.com: matchmaking by skill rating | +| **Mastery** | Meaningful feedback | Grammarly: specific, actionable writing suggestions | +| **Purpose** | Community contribution | Stack Overflow: helping others learn | +| **Purpose** | Collective goals | Foldit: solving protein structures for science | +| **Purpose** | Impact visibility | Ecosia: tree counter per user | + +### Gamification Audit + +| Question | If "No" | Action | +|----------|---------|--------| +| Can users choose which challenges to pursue? | No autonomy | Add challenge selection or opt-in | +| Does difficulty adapt to the user's skill? | No flow state | Implement adaptive difficulty | +| Is progress tied to genuine skill development? | Vanity metrics | Redesign progress to reflect real competence | +| Do users understand why the activity matters? | No purpose | Connect activities to meaningful outcomes | +| Would users engage without the rewards? | Extrinsic dependency | Reduce rewards, strengthen intrinsic design | + +## AMP Applied to Team Management and Incentives + +### The AMP Manager Framework + +| Principle | Traditional Manager (2.0) | AMP Manager (3.0) | +|-----------|--------------------------|-------------------| +| **Autonomy** | "Do it this way, by this time" | "Here's the goal. How you get there is your call." | +| **Mastery** | Annual performance review | Continuous feedback, stretch goals, learning budget | +| **Purpose** | "Hit these numbers" | "Here's why this work matters for our customers" | + +### Team Meeting Redesign + +| Meeting Element | Motivation 2.0 Version | Motivation 3.0 Version | +|----------------|----------------------|----------------------| +| **Status update** | "Report your metrics" | "What did you learn this week?" | +| **Goal setting** | "Here are your targets" | "What do you want to tackle next?" | +| **Problem solving** | "Here's what you should do" | "What approaches have you considered?" | +| **Recognition** | "Top performer this month is..." | "Who helped you grow this week?" | +| **Planning** | "Here's the roadmap you'll execute" | "What should we prioritize and why?" | + +### Incentive Redesign: From "If-Then" to "Now-That" + +Transform controlling incentive structures into autonomy-supportive ones. + +| Current "If-Then" | Transformed "Now-That" | Why It's Better | +|-------------------|----------------------|-----------------| +| "Hit 100% of quota, get 20% bonus" | Pay competitive base. Offer unexpected bonuses for exceptional work | Removes metric gaming; rewards genuine contribution | +| "Complete training by Friday, get gift card" | Make training genuinely useful. Celebrate completion with recognition | Learning becomes valuable in itself | +| "Log 40 hours, get paid" | Evaluate output, not hours. Offer flexible schedules | Focus shifts from attendance to results | +| "Refer a candidate, get $5,000" | Build a culture people want to recommend. Recognize referrers personally | Referrals come from genuine belief, not bounty hunting | +| "5-star customer rating, get bonus" | Train for genuine service. Share customer impact stories | Service becomes authentic, not performative | + +## AMP Applied to Onboarding + +### Product Onboarding + +| Stage | Motivation 2.0 (Extrinsic) | Motivation 3.0 (Intrinsic) | +|-------|---------------------------|---------------------------| +| **Welcome** | "Complete these 10 steps for a badge" | "Here's why this product exists and what you can build with it" | +| **First task** | "Click here, then here, then here" | "Choose what you'd like to explore first" | +| **Progress** | "3 of 10 steps complete" | "You just created your first [meaningful output]" | +| **Engagement** | "Come back tomorrow for a reward" | "Here's what you can do next (when you're ready)" | +| **Mastery** | "You've earned the beginner badge" | "You've learned [specific skill]. Ready to try [next challenge]?" | + +### Onboarding Checklist (AMP-Aligned) + +- [ ] Users understand the "why" before the "how" (purpose first) +- [ ] Users can choose their starting point (task autonomy) +- [ ] Users can skip or speed through content they already know (technique autonomy) +- [ ] The first meaningful accomplishment happens within 2 minutes (mastery signal) +- [ ] Difficulty increases gradually based on user behavior (adaptive mastery) +- [ ] The onboarding connects to a larger goal or community (purpose) +- [ ] No rewards are promised for completion (avoid extrinsic conditioning) +- [ ] The experience itself is valuable, not just a gate to the product + +### Employee Onboarding + +| Week | Motivation 2.0 Approach | Motivation 3.0 Approach | +|------|------------------------|------------------------| +| **Week 1** | Compliance paperwork, mandatory orientation videos | Meet the team, understand the mission, choose your first project | +| **Week 2** | Shadow someone, follow the manual | Pair with a mentor (self-selected), contribute something small | +| **Week 3** | More training modules, compliance tests | Ship something real, get feedback, adjust | +| **Week 4** | Formal evaluation of onboarding completion | Reflection: "What energized you? What do you want to learn next?" | + +## AMP Applied to Education and Learning Products + +### Motivation Failures in Traditional Education + +| Traditional Pattern | AMP Problem | Intrinsic Alternative | +|--------------------|-------------|----------------------| +| Grades as primary feedback | Extrinsic reward replaces love of learning | Narrative feedback on growth and next steps | +| Standardized curriculum for all | Zero task or technique autonomy | Choice boards, self-directed projects | +| One-pace-fits-all | No flow state (bored or anxious) | Adaptive pacing based on demonstrated understanding | +| Rank-ordered class lists | Competition replaces collaboration | Personal progress tracking | +| "Study this because it's on the test" | No purpose connection | "Study this because it lets you [meaningful outcome]" | + +### Learning Product Design Patterns + +| AMP Pillar | Design Pattern | Product Example | +|-----------|---------------|-----------------| +| **Autonomy** | Choose learning path | Coursera: select courses freely | +| **Autonomy** | Set own pace | Khan Academy: self-paced progress | +| **Autonomy** | Choose practice mode | Duolingo: stories, lessons, or practice | +| **Mastery** | Spaced repetition | Anki: optimize review timing | +| **Mastery** | Adaptive difficulty | Brilliant.org: problems scale to skill | +| **Mastery** | Skill visualization | Codecademy: skill tree progress | +| **Purpose** | Real-world application | freeCodeCamp: build projects for nonprofits | +| **Purpose** | Community teaching | Stack Overflow: learn by helping others | +| **Purpose** | Goal connection | Duolingo: "Learn Spanish to talk to your grandmother" | + +## AMP Applied to Health and Fitness Products + +### Common Motivation Failures + +| Extrinsic Approach | Why It Fails | AMP Alternative | +|-------------------|-------------|-----------------| +| Calorie counting as primary metric | Turns eating into accounting; kills food enjoyment | Focus on energy levels, how food makes you feel | +| Step count leaderboards | Discourages non-competitive users | Personal progress and adaptive goals | +| Before/after weight photos | Extrinsic appearance motivation fades | Focus on what your body can do (mastery) | +| Streak penalties | Anxiety-driven; one missed day = "I failed" | Celebrate consistency trends, not perfection | +| Social shame ("Your friend ran 5 miles") | Guilt-based motivation backfires | "Your friend ran 5 miles -- want to join a run together?" | + +### AMP Health Product Patterns + +| Pillar | Pattern | Implementation | +|--------|---------|----------------| +| **Autonomy** | Choose your workout style | Users select from yoga, running, weights, etc. | +| **Autonomy** | Flexible scheduling | "Work out when it fits your day" vs. "Your workout is at 7am" | +| **Autonomy** | Opt-in social features | Share if you want, compete if you want | +| **Mastery** | Progressive difficulty | Gradually harder workouts as fitness improves | +| **Mastery** | Skill milestones | "You can now do 10 pushups -- let's work toward 15" | +| **Mastery** | Form feedback | AI-powered form correction (Mirror, Tempo) | +| **Purpose** | Health narrative | "Build strength so you can play with your kids" | +| **Purpose** | Community challenges | "Together, our community ran 1M miles this month" | +| **Purpose** | Charity tie-ins | "Every mile you run, we donate $1 to [cause]" (Charity Miles) | + +## AMP Applied to Productivity Tools + +### Why Productivity Tools Lose Users + +Most productivity tools fail at retention because they rely on extrinsic mechanics (task completion streaks, productivity scores) instead of intrinsic motivation. + +| Extrinsic Trap | Why Users Abandon | AMP Fix | +|---------------|-------------------|---------| +| Productivity scores | Feels like surveillance, not support | Show what you accomplished, not how "productive" you were | +| Task completion gamification | Checking boxes replaces meaningful work | Help users connect tasks to goals that matter to them | +| Notification bombardment | Loss of control over attention | User-controlled notification cadence and channels | +| Rigid workflow enforcement | One-size-fits-all kills autonomy | Flexible, customizable workflows | +| Feature overload | Overwhelm prevents mastery | Progressive disclosure, learn as you go | + +### AMP Productivity Patterns + +| Pillar | Pattern | Example Tool | +|--------|---------|-------------| +| **Autonomy** | Customizable workspace | Notion: build any system you want | +| **Autonomy** | Multiple input methods | Todoist: keyboard, voice, email, API | +| **Autonomy** | Integration choice | Zapier: connect the tools you prefer | +| **Mastery** | Templates that teach | Airtable: templates that demonstrate best practices | +| **Mastery** | Progressive complexity | Figma: simple tools first, advanced features discoverable | +| **Mastery** | Keyboard shortcut progression | VS Code: visual actions first, keyboard shortcuts as mastery grows | +| **Purpose** | Goal connection | Asana: link tasks to team objectives | +| **Purpose** | Impact visualization | GitHub: contribution graph shows collective building | +| **Purpose** | Team awareness | Linear: shared progress toward product milestones | + +## Compensation Design: Pay Enough to Take Money Off the Table + +### Pink's Compensation Framework + +**Step 1: Ensure baseline fairness.** Pay at or above market rate. If compensation is perceived as unfair, no amount of AMP design will overcome resentment. + +**Step 2: Remove contingent rewards.** Eliminate or minimize "if-then" bonus structures for creative and cognitive work. + +**Step 3: Focus on AMP.** Once money is off the table, invest in autonomy, mastery, and purpose. + +### Compensation Models Compared + +| Model | AMP Alignment | Risk | +|-------|--------------|------| +| **High base, no bonus** | Strong autonomy (no metric gaming) | May feel "flat" to high performers | +| **High base + profit sharing** | Good purpose alignment (shared success) | Individuals can't control company profit | +| **High base + discretionary bonus** | Good if truly discretionary ("now-that") | Becomes "if-then" if predictable | +| **Low base + high commission** | Poor: creates extrinsic dependency | Short-term thinking, gaming, burnout | +| **Salary + equity** | Good purpose alignment (long-term) | Only motivating if equity is meaningful | + +### Pay Transparency + +| Approach | Benefit | Risk | +|----------|---------|------| +| Full transparency (Buffer model) | Eliminates pay-based resentment; signals trust | Difficult to implement retroactively; social comparison | +| Band transparency | People know the range for their role | Less trust than full, but easier to manage | +| No transparency | None | Breeds suspicion, resentment, and gossip | + +## "If-Then" to "Now-That" Transformation Examples + +### Sales Team + +| Before (If-Then) | After (Now-That) | +|-------------------|-----------------| +| "Close 10 deals this month, get $2,000 bonus" | Competitive base salary. Quarterly recognition for exceptional contributions. Unexpected bonuses for going above and beyond. | +| **Result:** Reps rush low-quality deals, offer unauthorized discounts, compete against teammates | **Result:** Reps focus on customer relationships, collaborate on complex deals, build long-term value | + +### Engineering Team + +| Before (If-Then) | After (Now-That) | +|-------------------|-----------------| +| "Ship feature by Friday, get spot bonus" | Fair salary. 20% time for self-directed projects. After shipping, team celebration and unexpected bonus for exceptional effort. | +| **Result:** Corners cut, technical debt accumulates, quality suffers | **Result:** Sustainable pace, higher quality, intrinsic pride in work | + +### Customer Support Team + +| Before (If-Then) | After (Now-That) | +|-------------------|-----------------| +| "Resolve 50 tickets/day, maintain performance rating" | Competitive base. Autonomy in how to handle customers. After exceptional quarters, surprise team experience or individual recognition. | +| **Result:** Rush through tickets, low resolution quality, gaming metrics | **Result:** Genuine care for customers, creative problem-solving, higher satisfaction scores | + +## Implementation Checklist for AMP in Any Product + +### Phase 1: Audit Current State + +- [ ] List all extrinsic reward mechanics currently in the product +- [ ] Identify which rewards are "if-then" (announced, contingent) vs. "now-that" (unexpected) +- [ ] Survey users: "Would you use this product without [reward X]?" +- [ ] Map which features support autonomy, mastery, or purpose (and which don't) +- [ ] Identify the top 3 motivation killers in the current experience + +### Phase 2: Remove or Transform Extrinsic Mechanics + +- [ ] Convert "if-then" rewards to "now-that" where possible +- [ ] Remove rewards that have become expected (and thus extrinsic) +- [ ] Eliminate punitive mechanics (losing progress, streak penalties) +- [ ] Stop gamifying activities that should be intrinsically motivating +- [ ] Preserve rewards only for genuinely algorithmic, routine tasks + +### Phase 3: Build Intrinsic Motivation + +- [ ] Add at least one autonomy feature (choice, customization, flexibility) +- [ ] Add at least one mastery feature (progress tracking, adaptive difficulty, feedback) +- [ ] Add at least one purpose feature (impact visibility, mission connection, community) +- [ ] Ensure onboarding leads with purpose ("why"), not mechanics ("how") +- [ ] Design feedback systems that are immediate, specific, and growth-oriented + +### Phase 4: Measure and Iterate + +- [ ] Track engagement without extrinsic rewards (true intrinsic engagement) +- [ ] Monitor retention after removing/changing reward systems +- [ ] Survey for autonomy satisfaction ("Do you feel in control?") +- [ ] Survey for mastery satisfaction ("Are you getting better at something?") +- [ ] Survey for purpose connection ("Does this product connect to something you care about?") +- [ ] A/B test intrinsic vs. extrinsic versions of features diff --git a/.agents/skills/drive-motivation/references/autonomy.md b/.agents/skills/drive-motivation/references/autonomy.md new file mode 100644 index 00000000..28a0a176 --- /dev/null +++ b/.agents/skills/drive-motivation/references/autonomy.md @@ -0,0 +1,247 @@ +# Autonomy: The Desire to Direct Our Own Lives + +Autonomy is the foundational pillar of intrinsic motivation. It is not independence or isolation -- it is the sense that you are acting with volition and choice, even within constraints. Research consistently shows that when people feel autonomous, they are more engaged, more productive, more creative, and healthier. This reference provides actionable frameworks for designing autonomy into products, teams, and organizations. + +## The Four T's of Autonomy + +Daniel Pink identifies four dimensions where autonomy matters. Organizations and products that support all four unlock the deepest engagement. + +### Task Autonomy: What Do I Work On? + +Control over what you spend your time and energy on. + +| Implementation | Description | Real-World Example | +|---------------|-------------|-------------------| +| 20% time | Dedicate a portion of work to self-directed projects | Google (Gmail, AdSense, Google News emerged from 20% time) | +| ShipIt days | 24-hour hack events where employees choose their projects | Atlassian's ShipIt (formerly FedEx days) | +| Choice boards | Let users/employees pick from a menu of tasks | Basecamp's "choose your own project" for non-core work | +| Self-selected goals | Individuals propose their own OKRs | W.L. Gore & Associates: "commitments" chosen by employees | + +### Time Autonomy: When Do I Work? + +Control over scheduling, pacing, and rhythm. + +| Implementation | Description | Real-World Example | +|---------------|-------------|-------------------| +| ROWE | Results-Only Work Environment -- no required hours | Best Buy corporate (before reversal); many remote-first startups | +| Flexible core hours | Required overlap window, flexible otherwise | Buffer: 4-hour overlap, rest is flexible | +| No-meeting days | Protected blocks for deep work | Shopify's "no meeting Wednesdays" | +| Self-paced deadlines | User chooses their own timeline | Coursera: set your own course schedule | + +### Technique Autonomy: How Do I Do It? + +Control over methods, tools, and approaches. + +| Implementation | Description | Real-World Example | +|---------------|-------------|-------------------| +| Tool freedom | Choose your own IDE, OS, software stack | GitHub: developers choose their own tools | +| Method freedom | Multiple valid approaches to the same goal | Spotify squads: each team picks its own engineering practices | +| Process flexibility | Adapt workflow to individual style | Valve: flat hierarchy, no prescribed process | +| Personalization | Users customize how they interact with a product | Notion: build any workflow you want | + +### Team Autonomy: Who Do I Work With? + +Control over collaborators, mentors, and group composition. + +| Implementation | Description | Real-World Example | +|---------------|-------------|-------------------| +| Self-forming teams | People choose their project teams | Valve's "desks on wheels" -- move to any project | +| Mentor selection | Choose your own mentor or coach | Deloitte's self-selected mentorship program | +| Collaboration choice | Opt into working groups | Open-source communities: contribute to any project | +| Peer hiring | Team members interview and approve new members | Whole Foods: teams vote on new hires after trial period | + +## Autonomy in Product Design + +### Autonomy Enablers + +Design patterns that increase user autonomy and intrinsic motivation. + +| Pattern | How It Works | Example | +|---------|-------------|---------| +| **Progressive disclosure** | Show basics first, let users unlock complexity | Figma: simple tools visible, advanced features discoverable | +| **Customizable dashboards** | Users arrange their own information architecture | Jira: custom boards, filters, and views | +| **Opt-in features** | Features are available but never forced | Slack: optional app integrations, notification settings | +| **Multiple paths** | More than one way to achieve the same goal | Adobe Photoshop: keyboard shortcuts, menus, toolbar, search | +| **User-created workflows** | Users build their own automations | Zapier, IFTTT: user-defined triggers and actions | +| **Preference controls** | Granular settings for experience customization | YouTube: playback speed, caption preferences, theme | +| **Skip/dismiss options** | Users can bypass content they don't need | Most apps: "Skip tutorial" or "Remind me later" | +| **Undo/reversibility** | Decisions feel safe because they can be reversed | Gmail: "Undo send" eliminates fear of commitment | + +### Autonomy Killers + +Design patterns that strip user autonomy and reduce motivation. + +| Anti-Pattern | Why It Hurts | Better Alternative | +|-------------|-------------|-------------------| +| **Forced tutorials** | "You must do this before proceeding" | Optional tutorials with skip option | +| **Mandatory notifications** | User has no control over interruptions | Granular notification preferences, DND mode | +| **Linear-only flows** | Only one path through the experience | Branching paths, choose-your-own-order | +| **No customization** | One-size-fits-all experience | Themes, layouts, feature toggles | +| **Irreversible actions** | Fear of making mistakes reduces exploration | Undo, version history, drafts | +| **Forced social sharing** | "Share to continue" or required profiles | Optional sharing, anonymous modes | +| **Dark patterns** | Tricking users into choices they didn't intend | Clear options with honest framing | +| **Auto-play/auto-scroll** | Content consumption without consent | Play/scroll initiated by user action | + +## Autonomy in Team Management + +### Results-Only Work Environment (ROWE) + +Developed by Cali Ressler and Jody Thompson at Best Buy headquarters. + +**Core principle:** Employees are evaluated solely on results, not on when or where they work. + +**ROWE rules:** +1. Every meeting is optional +2. There are no required schedules +3. Nobody is judged on how many hours they work +4. Work happens anywhere, anytime +5. The only thing that matters is results + +**Results at Best Buy:** Productivity increased 35%. Voluntary turnover dropped 90% in participating departments. Employee satisfaction scores increased significantly. + +**Why it eventually ended:** New CEO Hubert Joly reversed ROWE in 2013, favoring in-office collaboration. The reversal itself demonstrated a key tension: autonomy requires sustained organizational commitment. + +### 20% Time and FedEx Days + +**Google's 20% time:** Engineers could spend one day per week on self-directed projects. Products that emerged: Gmail, Google News, AdSense, Google Suggest. Not all employees used it (some were too busy with core work), but its existence signaled trust and autonomy. + +**Atlassian's ShipIt (FedEx Days):** Quarterly 24-hour sprints where employees work on anything they want, provided they "deliver" something by the next day (like FedEx). Results are presented to the entire company. Many ShipIt projects have become actual Atlassian features. + +### Autonomy-Supportive Management Behaviors + +| Behavior | Description | +|----------|-------------| +| Explain the "why" | Give context for decisions and constraints | +| Acknowledge feelings | Recognize that tasks may not be enjoyable | +| Offer choice within constraints | "Here's the goal -- how you get there is your call" | +| Minimize controlling language | Avoid "must," "should," "have to" when possible | +| Ask questions before giving answers | "What do you think?" before prescribing solutions | +| Set boundaries, not micromanagement | Define the sandbox, not every action within it | + +## Case Studies + +### Atlassian ShipIt + +**Context:** Australian software company wanted to foster innovation without top-down mandates. + +**Implementation:** Quarterly 24-hour "ShipIt" events (originally called FedEx Days). Employees form ad-hoc teams, work on anything they choose, and present results the next day. The company provides food, beverages, and celebration. + +**Results:** +- Dozens of features shipped to customers originated from ShipIt projects +- Employee engagement scores consistently high +- Recruitment advantage: candidates cite ShipIt as a reason they want to work at Atlassian +- Cultural signal: "We trust you to know what's worth building" + +### Best Buy ROWE + +**Context:** Best Buy corporate headquarters experienced high turnover and low morale despite competitive compensation. + +**Implementation:** Gradual department-by-department rollout of ROWE. No required hours, no required presence, purely results-based evaluation. + +**Results:** +- 35% productivity increase in ROWE departments +- 90% reduction in voluntary turnover +- Employees reported higher satisfaction, less stress, better work-life balance +- Demonstrated that autonomy, not perks, drives retention + +### Zappos Holacracy + +**Context:** Online shoe retailer wanted to eliminate bureaucracy and empower employees. + +**Implementation:** Adopted holacracy (self-management framework) in 2013. No traditional managers. Employees organized into self-governing "circles." + +**Results (mixed):** +- Initial excitement about self-direction +- 14% of employees left during the transition (offered buyouts) +- Some teams thrived; others struggled without clear guidance +- Lesson: autonomy requires support structures, not just removal of hierarchy + +## Balancing Autonomy with Alignment + +Autonomy without direction is chaos. The goal is **aligned autonomy**: people have freedom in how they work, but clarity on what matters. + +### The Alignment Framework + +| Element | Leader Provides | Individual Chooses | +|---------|----------------|-------------------| +| **Vision** | Where we're going | How to contribute | +| **Goals** | What success looks like | How to achieve it | +| **Values** | Behavioral guardrails | Daily decisions | +| **Resources** | Budget, tools, access | How to deploy them | +| **Feedback** | Performance signals | How to respond and adjust | + +### Guardrails That Enable Autonomy + +- **Clear objectives:** People need to know what "done" looks like +- **Transparent constraints:** Budget limits, deadlines, and non-negotiables stated upfront +- **Accessible information:** Autonomy requires context; hoard information and autonomy fails +- **Psychological safety:** Freedom to fail without punishment +- **Regular check-ins:** Short, non-controlling syncs that provide context and remove blockers + +## Autonomy Audit Checklist for Products + +Use this checklist to evaluate whether your product supports user autonomy. + +### User Control + +- [ ] Users can skip onboarding or tutorials +- [ ] Users can choose the order of tasks or content +- [ ] Users can customize the interface (themes, layout, density) +- [ ] Users have granular notification controls (type, frequency, channel) +- [ ] Users can undo or reverse significant actions +- [ ] Users can export their data +- [ ] Users can delete their account and data + +### Flexibility + +- [ ] Multiple paths exist for completing core tasks +- [ ] Advanced features are available but not forced on beginners +- [ ] Users can set their own goals or targets +- [ ] The product adapts to individual workflows (or allows manual adaptation) +- [ ] Users can integrate with tools of their choice + +### Absence of Coercion + +- [ ] No forced social sharing or public profile requirements +- [ ] No dark patterns or manipulative consent flows +- [ ] No mandatory features that cannot be disabled +- [ ] No punitive mechanics for non-engagement (e.g., losing progress for inactivity) +- [ ] No artificial urgency that pressures decisions + +## Autonomy Audit Checklist for Teams and Organizations + +### Task Autonomy + +- [ ] Team members have input on what projects they work on +- [ ] There is dedicated time for self-directed work (20% time, hack days) +- [ ] Individuals can propose new initiatives +- [ ] People can say "no" to projects without career penalty + +### Time Autonomy + +- [ ] Flexible work hours exist (or ROWE principles apply) +- [ ] There are protected blocks for deep work (no-meeting days or hours) +- [ ] People choose when to take breaks and vacation +- [ ] Deadlines are negotiated, not dictated, when possible + +### Technique Autonomy + +- [ ] Team members choose their own tools and methods +- [ ] Multiple approaches to the same problem are encouraged +- [ ] Process exists to serve the team, not to control it +- [ ] "How" decisions are made by the person closest to the work + +### Team Autonomy + +- [ ] People have input on who they collaborate with +- [ ] Cross-functional teams form organically around problems +- [ ] New hires meet the team before a final offer is extended +- [ ] Mentorship and coaching relationships are self-selected + +### Cultural Indicators + +- [ ] Managers explain "why" behind decisions routinely +- [ ] Controlling language ("must," "should") is rare in leadership communication +- [ ] Mistakes are treated as learning opportunities, not punishable offenses +- [ ] Information flows freely (no hoarding of context by managers) +- [ ] Trust is the default; surveillance and tracking are minimal diff --git a/.agents/skills/drive-motivation/references/case-studies.md b/.agents/skills/drive-motivation/references/case-studies.md new file mode 100644 index 00000000..d6e1de1e --- /dev/null +++ b/.agents/skills/drive-motivation/references/case-studies.md @@ -0,0 +1,199 @@ +# Case Studies: Motivation Science in Practice + +Six real-world cases where motivation science -- applied or violated -- produced measurable outcomes. Each follows the same structure: context, motivation challenge, AMP application (or failure), results, and transferable lessons. The final section identifies cross-cutting patterns and common failure modes. + +## Case Study 1: Atlassian ShipIt Days (Autonomy) + +**Organization:** Atlassian, Australian enterprise software company (Jira, Confluence, Trello, Bitbucket). Founded 2002. Over 10,000 employees. + +**Motivation Challenge:** Atlassian wanted to foster innovation without top-down mandates or innovation committees. Traditional hackathons at other companies felt forced, had narrow scopes defined by management, and produced ideas that never shipped. + +**AMP Application -- Primary lever: Autonomy (Task)** + +Atlassian created "ShipIt" (originally called FedEx Days because you had to "deliver" overnight). + +| Element | Design Choice | AMP Principle | +|---------|--------------|---------------| +| Project selection | Employees choose anything they want to build | Task autonomy | +| Team formation | Self-selected teams, any combination of roles | Team autonomy | +| Timeline | 24 hours, start Thursday afternoon, present Friday | Time constraint creates flow conditions | +| Presentation | All projects demoed to entire company | Purpose (sharing with community) | +| Judging | Peer voting, not management selection | Autonomy (community decides) | +| Implementation | Winning projects often get development time | Mastery (see your idea become real) | +| Frequency | Quarterly | Regular enough to sustain engagement | + +**What Atlassian did NOT do:** No cash prizes. No restriction to business priorities. No manager approval required. No mandatory participation. + +**Results:** Dozens of customer-facing features originated from ShipIt. Employee engagement consistently high, with ShipIt cited as a top cultural element. Candidates mention ShipIt as a reason they want to join. Serves as a low-cost R&D pipeline with zero bureaucracy. + +**Lessons:** +1. **Autonomy without prizes works.** Intrinsic satisfaction of building, presenting, and potentially shipping is more motivating than cash. +2. **Constraints enable creativity.** The 24-hour limit created urgency and flow conditions. +3. **Regularity matters.** Quarterly events build cultural expectation without losing novelty. +4. **Peer judgment > management judgment.** Community voting creates shared ownership. + +## Case Study 2: 3M's 15% Time (Autonomy to Mastery) + +**Organization:** 3M (Minnesota Mining and Manufacturing). Global science and manufacturing company. Over 90,000 employees. Founded 1902. + +**Motivation Challenge:** 3M needed continuous new product innovations. Their business model required that 30% of revenue come from products introduced in the last four years. Traditional R&D management was too slow and too narrow. + +**AMP Application -- Primary lever: Autonomy (Task + Technique)** + +Starting in the 1950s, 3M let technical employees spend 15% of work time on self-chosen projects. + +| Element | Design Choice | AMP Principle | +|---------|--------------|---------------| +| Time allocation | 15% of work hours for self-directed exploration | Time and task autonomy | +| Approval required | None for exploration phase | Technique autonomy | +| Funding | Small grants through informal channels | Removes barriers to experimentation | +| Failure tolerance | "Thou shalt not kill ideas" as cultural principle | Mastery mindset (failure = learning) | +| Knowledge sharing | Internal technical forums, cross-divisional sharing | Purpose (advancing collective knowledge) | + +**Results:** Post-it Notes emerged from Spencer Silver's "failed" adhesive combined with Art Fry's 15% project -- now a multi-billion dollar product line. Numerous medical and industrial innovations came from self-directed exploration. 3M sustained 30%+ revenue from new products for decades. + +**Lessons:** +1. **Autonomy produces serendipity.** Directed R&D would never have assigned "invent a weak adhesive." +2. **Time autonomy requires organizational patience.** 15% time produces results in years, not quarters. +3. **Cross-pollination needs autonomy.** Silver's adhesive only became Post-it Notes because Fry had freedom to explore an unrelated application. +4. **Cultural norms matter more than formal policies.** The policy only works because 3M genuinely tolerates failure. + +## Case Study 3: Duolingo (Mastery + Purpose, with Extrinsic Tension) + +**Organization:** Duolingo, language learning platform. Founded 2011. Over 500 million registered users. + +**Motivation Challenge:** Language learning has one of the highest dropout rates of any self-improvement activity. Most people quit within weeks. Duolingo needed daily engagement for months or years. + +**AMP Application -- Primary levers: Mastery + Purpose** + +| Element | Design Choice | AMP Principle | +|---------|--------------|---------------| +| Adaptive difficulty | AI adjusts question difficulty based on performance | Mastery (flow channel maintenance) | +| Skill tree | Visual map of language competencies | Mastery (progress visibility) | +| Immediate feedback | Instant correction with explanation | Mastery (deliberate practice) | +| Course choice | Users choose language and topics | Autonomy (task) | +| Mission framing | "Free language education for the world" | Purpose (democratization) | +| Stories feature | Narrative-based learning with cultural context | Purpose (human connection) | + +**The extrinsic tension:** Duolingo also uses streaks (can become anxiety-driven), leaderboards (discourages non-competitive users), gems/lingots (extrinsic currency), and streak freezes (monetizes the anxiety the streak created). + +**Results:** 500M+ registered users, 30M+ daily active users, higher retention than most educational apps. Research shows effectiveness for basic proficiency. Over $500M annual revenue. + +**Lessons:** +1. **Mastery design is the core engine.** Adaptive difficulty and immediate feedback keep learning effective. +2. **Streaks are a double-edged sword.** They drive daily habits but risk shifting motivation from "I want to learn" to "I can't break my streak." +3. **Extrinsic and intrinsic can coexist, carefully.** Success comes from a strong intrinsic core wrapped with extrinsic elements. The risk is the extrinsic layer overwhelming the intrinsic core. + +## Case Study 4: Best Buy ROWE (Autonomy) + +**Organization:** Best Buy, American consumer electronics retailer. Corporate headquarters in Richfield, Minnesota. + +**Motivation Challenge:** High turnover, low morale, and presenteeism (employees physically present but disengaged) despite competitive compensation. + +**AMP Application -- Primary lever: Autonomy (Time + Technique)** + +Cali Ressler and Jody Thompson developed ROWE (Results-Only Work Environment) and piloted it at Best Buy headquarters starting in 2003. + +| ROWE Principle | Traditional Approach | ROWE Approach | +|---------------|---------------------|---------------| +| Work hours | 9-5, Monday-Friday | Work whenever you want | +| Work location | At your desk | Work wherever you want | +| Meetings | Mandatory attendance | Every meeting is optional | +| Vacation | Request and approval needed | Take time off when you want | +| Measurement | Hours worked, face time | Results delivered | + +**Results:** Productivity increased 35% across participating departments. Voluntary turnover dropped 90%. Employee satisfaction increased significantly. Reduced stress and fewer sick days. In 2013, new CEO Hubert Joly reversed ROWE, requiring return to office. + +**Lessons:** +1. **Autonomy produces measurable results.** 35% productivity increase and 90% turnover reduction are among the most compelling data points for workplace autonomy. +2. **ROWE requires cultural commitment.** When leadership changed, the program was reversed. Autonomy initiatives depending on a single champion are fragile. +3. **Results measurement must precede autonomy.** ROWE only works when "results" are clearly defined. Departments with ambiguous outputs struggled. +4. **Taking away autonomy is worse than never granting it.** Employees who experienced ROWE and lost it reported higher dissatisfaction than those who never had it. + +## Case Study 5: Wikipedia (Purpose-Driven Contribution) + +**Organization:** Wikipedia, free online encyclopedia. Founded 2001. Over 60 million articles in 300+ languages. Entirely community-written and edited. + +**Motivation Challenge:** Create and maintain the largest encyclopedia in history using entirely unpaid volunteer labor. No salary, no equity, no commissions. + +**AMP Application -- Primary lever: Purpose, supported by Autonomy and Mastery** + +| Element | Design Choice | AMP Principle | +|---------|--------------|---------------| +| Mission | "Free access to the sum of all human knowledge" | Purpose (profound and specific) | +| Contribution model | Anyone can edit any article | Autonomy (total task/technique freedom) | +| Recognition | Edit history, contribution page, barnstars | Mastery (visible growth) | +| Governance | Community-developed policies, elected administrators | Autonomy (self-governance) | +| Revenue model | Donations only, no advertising | Purpose (mission integrity) | + +**Results:** 60M+ articles across 300+ languages. ~300,000 monthly active editors. Accuracy rivaling traditional encyclopedias. Top-10 global website. 20+ years of operation on ~$170M annual budget. + +**Lessons:** +1. **Purpose can replace payment entirely.** Hundreds of thousands contribute billions of hours because they believe in the mission. +2. **Autonomy is the mechanism.** Anyone can edit anything -- no gatekeeper, no approval process. +3. **Mission integrity matters.** Refusing advertising maintains credibility and editor trust. Ads would erode volunteer motivation. +4. **Scale requires governance, not management.** Community-developed policies provide alignment without hierarchy. + +## Case Study 6: The Motivation Destroyer -- A Cautionary Tale + +**Organization:** Composite case based on documented patterns at multiple organizations (Sears, Yahoo, Microsoft under stack-ranking) that implemented aggressive performance-based incentives. + +**What They Did (Motivation 2.0 Playbook):** +- Stack-ranked engineers (bottom 10% on performance improvement plans) +- Set escalating quarterly sales targets with escalating bonuses +- Required cross-team collaboration metrics for bonus eligibility +- Displayed real-time individual performance leaderboards +- Tied up to 40% of compensation to individual metrics + +**What Actually Happened:** + +| Initiative | Actual Outcome | AMP Violation | +|-----------|---------------|---------------| +| Stack ranking | Engineers avoided hard projects, hoarded knowledge | Killed mastery pursuit | +| Quarterly targets | Sales front-loaded easy deals, gamed timing | Short-term thinking (Flaw 7) | +| Forced collaboration | Fake cross-team meetings, checkbox compliance | Killed autonomy, encouraged cheating | +| Leaderboards | Top performers territorial; bottom demoralized | Crushed intrinsic motivation | +| Performance bonuses | Optimized measurable metrics, ignored unmeasured work | Narrowed focus (Flaw 2) | + +**The cascade:** Aggressive incentives led to metric gaming, which led to more metrics, which led to more gaming and less trust, which led to surveillance, which collapsed autonomy, which killed intrinsic motivation. Only extrinsic motivation remained, requiring bigger incentives. The cycle repeated until talent left. + +**Results:** Short-term revenue briefly increased. Innovation declined significantly. Collaboration decreased despite metrics. Voluntary turnover among top performers rose 25%+. Long-term revenue declined. + +**Lessons:** +1. **Incentives that measure everything motivate nothing.** People optimize the measurement system, not the actual work. +2. **Stack ranking destroys collaboration.** Microsoft famously abandoned it in 2013 after years of internal damage. +3. **The best people leave first.** Top performers have the most options and the lowest tolerance for controlling environments. +4. **Recovery is slow.** Once intrinsic motivation culture is destroyed, rebuilding takes years. + +## Cross-Cutting Patterns + +### What Separates Intrinsic from Extrinsic Motivation Design + +| Dimension | Extrinsic Design | Intrinsic Design | +|-----------|-----------------|-----------------| +| **Starting question** | "How do we get people to do X?" | "How do we create conditions where people want to do X?" | +| **Control locus** | Organization controls behavior | Individual controls behavior; organization provides context | +| **Feedback purpose** | Judgment and ranking | Growth and improvement | +| **Failure treatment** | Punishment or consequence | Learning opportunity | +| **Time horizon** | Quarterly or shorter | Years or longer | +| **Sustainability** | Requires escalation | Self-renewing through growth | + +### Common Motivation Design Failures + +| Failure | Root Cause | Prevention | +|---------|-----------|------------| +| Gamification that doesn't engage | Extrinsic mechanics on uninteresting core | Fix the core experience first | +| Innovation programs producing nothing | Too many controls and approval gates | Give genuine autonomy; accept most experiments fail | +| Engagement spikes then crashes | Extrinsic triggers that don't build habit | Build intrinsic value first | +| Retention efforts that fail | Trying to retain with money, not meaning | Ensure AMP is present | +| Culture initiatives that feel hollow | Values don't match policies | Align actions with words | + +### The AMP Test: Five Questions for Any Motivation System + +| Question | Healthy Answer | Unhealthy Answer | +|----------|---------------|------------------| +| Would people do this without the reward? | "Yes, many would" | "No, the reward is the only reason" | +| Does the system trust people by default? | "Yes, we assume good intent" | "No, we monitor and verify" | +| Can individuals shape their experience? | "Yes, there's meaningful choice" | "No, the path is predetermined" | +| Is failure treated as learning? | "Yes, we analyze and adjust" | "No, failure has consequences" | +| Can people articulate why it matters? | "Yes, they connect to the mission" | "No, they just know the metrics" | diff --git a/.agents/skills/drive-motivation/references/extrinsic-rewards.md b/.agents/skills/drive-motivation/references/extrinsic-rewards.md new file mode 100644 index 00000000..cd84d60a --- /dev/null +++ b/.agents/skills/drive-motivation/references/extrinsic-rewards.md @@ -0,0 +1,253 @@ +# The Seven Deadly Flaws of Extrinsic Rewards + +Extrinsic rewards -- bonuses, prizes, commissions, points, badges -- are the default tool organizations reach for when they want to change behavior. The research is clear: for any work requiring cognitive effort, creativity, or judgment, extrinsic "if-then" rewards either fail to improve performance or actively make it worse. This reference provides a deep dive into the seven mechanisms by which rewards backfire, when they do work, and how to design reward systems that minimize damage. + +## Flaw 1: Extinguish Intrinsic Motivation + +When people already find a task interesting, adding an external reward reduces their desire to do it once the reward disappears. + +### The Research + +**Deci (1969):** College students solved Soma puzzles. Group A was paid in session two; Group B was never paid. In session three (no payment for either), Group A spent significantly less free time on the puzzles. Payment had turned play into work. + +**Lepper, Greene, & Nisbel (1973):** Preschoolers who already liked drawing were divided into three groups. The "expected reward" group was told they'd get a certificate for drawing. Two weeks later, these children drew 50% less than children who received no reward or an unexpected reward. The expected reward had undermined what was previously spontaneous enjoyment. + +**Meta-analysis by Deci, Koestner, & Ryan (1999):** Reviewed 128 studies and found that tangible, expected, contingent rewards significantly undermine intrinsic motivation for interesting tasks. The effect is robust across ages, settings, and cultures. + +### Mechanism + +The cognitive shift is called the **overjustification effect**. When an external reason is added to an activity that already has an internal reason, the brain recategorizes the activity: "I must be doing this for the reward, not because I enjoy it." Remove the reward and the internal reason has been weakened. + +### Product Implications + +| Scenario | What Happens | Example | +|----------|-------------|---------| +| Paying users to write reviews | Users stop writing reviews without payment | Early Amazon Vine program churn | +| Points for every login | Users login for points, not value | Engagement drops when points system changes | +| Bonuses for feature usage | Feature becomes "work" | Enterprise software with mandatory adoption bonuses | + +## Flaw 2: Diminish Performance + +External rewards narrow focus, which helps for simple tasks but hurts for tasks requiring creative problem-solving. + +### The Candle Problem (Glucksberg, 1962) + +Participants were given a candle, a box of thumbtacks, and matches. The goal: attach the candle to the wall so wax doesn't drip on the table. The solution requires creative insight -- empty the box, tack it to the wall, place the candle inside. + +- **Group offered cash rewards** for fast solving: took **3.5 minutes longer** on average +- Rewards narrowed their focus; they couldn't see the box as anything other than a container for tacks +- When the tacks were presented **outside** the box (making the solution obvious/algorithmic), the rewarded group solved faster + +This is the core finding: rewards help with algorithmic tasks (clear path to solution) and hurt with heuristic tasks (requiring exploration and insight). + +### The London School of Economics Review (2009) + +An analysis of 51 studies of corporate pay-for-performance plans found that "financial incentives can result in a negative impact on overall performance." The pattern held across industries and compensation structures. + +### Product Implications + +- Reward systems that create urgency (countdown timers, limited-time bonuses) narrow user focus and reduce exploration +- Competition-based features (leaderboards with prizes) reduce the creative solutions users discover +- Gamification that rewards speed over quality drives shallow engagement + +## Flaw 3: Crush Creativity + +Rewards constrain the mental space needed for creative work by directing attention toward the reward and away from open exploration. + +### The Research + +**Amabile (1985):** Artists who created commissioned (rewarded) work were rated by expert panels as significantly less creative than when the same artists created non-commissioned work. The quality of execution was equivalent; only creativity suffered. + +**McGraw & McCullers (1979):** Participants rewarded for solving problems continued to use rote strategies even after the problems changed and required new approaches. The reward locked them into existing patterns. + +### Why This Matters for Product Design + +- Feature bounties and hackathon prizes can reduce the creativity of submissions +- "Fastest to complete" challenges in learning products discourage experimentation +- Reward-driven A/B testing (rewarding teams for wins) can reduce willingness to run bold experiments + +## Flaw 4: Crowd Out Good Behavior + +When you attach a financial value to a behavior that was previously governed by social or moral norms, people shift from a social framework to a market framework. + +### The Daycare Study (Gneezy & Rustichelli, 2000) + +A daycare in Haifa, Israel, introduced a fine for parents who picked up children late. The result: **late pickups doubled**. Parents reframed lateness from a moral failing ("I'm inconveniencing the teacher") to a market transaction ("I'm paying for extra time"). When the fine was later removed, late pickups stayed high -- the social norm had been permanently damaged. + +### The Blood Donation Effect (Titmuss, 1970; Mellstrom & Johannesson, 2008) + +When blood donors were offered small payments, donation rates dropped -- especially among women. Payment crowded out the altruistic motivation. The act shifted from "generous contribution" to "low-paying job." + +### Product Implications + +| Good Behavior | Reward Introduced | Result | +|--------------|-------------------|--------| +| Community help (forums) | Points per answer | Quantity up, quality down; helpful users leave | +| User referrals (organic) | Cash per referral | Spam referrals replace genuine recommendations | +| Content creation (passion) | Pay per post | Clickbait replaces thoughtful content | + +## Flaw 5: Encourage Cheating, Shortcuts, and Unethical Behavior + +When rewards are tied to specific outcomes, people optimize for the metric -- even through dishonest means. + +### Case Studies + +**Wells Fargo (2016):** Employees were given aggressive sales targets with bonuses. They responded by opening over 3.5 million fake accounts without customer consent. The reward system didn't create bad people; it created an environment where good people did bad things. + +**Sears Auto Centers (1992):** Mechanics were given minimum repair quotas. They began recommending unnecessary repairs. California's Department of Consumer Affairs found systematic overcharging driven entirely by the incentive structure. + +**Atlanta Public Schools (2009):** Teachers and administrators altered standardized test scores after bonuses were tied to test performance. 178 educators were implicated. The reward system made cheating the rational economic choice. + +### The Pattern + +``` +Specific metric target + Reward for hitting it = Optimized metric (by any means) +``` + +### Product Implications + +- Rewarding users for "completing" profiles leads to fake data entry +- Paying for app reviews leads to fake reviews +- Rewarding content volume leads to AI-generated spam +- Referral bonuses lead to self-referral fraud + +## Flaw 6: Become Addictive + +Extrinsic rewards follow the same habituation curve as other stimuli: the same reward produces diminishing satisfaction over time, requiring escalation. + +### The Hedonic Treadmill in Compensation + +Last year's bonus becomes this year's expectation. Research by Kahneman and Deaton (2010) showed that while emotional well-being rises with income up to approximately $75,000/year (adjusted for inflation), it plateaus beyond that. Yet bonus expectations continue to escalate. + +### The Escalation Pattern + +| Year | Bonus | Satisfaction | Expectation for Next Year | +|------|-------|-------------|--------------------------| +| 1 | $5,000 | High | $5,000+ | +| 2 | $5,000 | Neutral | $7,000+ | +| 3 | $5,000 | Negative | $10,000+ | +| 4 | $7,000 | Moderate | $10,000+ | + +The same dynamic applies in products: a daily login reward that excited users in month one becomes an expectation by month three and a grievance if removed by month six. + +### Product Implications + +- Points systems require inflation management (users expect more points over time) +- Discount-based engagement (coupons, sales) trains users to wait for deals +- Streak rewards lose motivational power and become anxiety-driven obligations + +## Flaw 7: Foster Short-Term Thinking + +Rewards orient behavior toward the reward period and away from long-term value creation. + +### The Research + +**Laverty (1996):** Quarterly earnings incentives drive executives to sacrifice long-term R&D for short-term results. Companies with heavy short-term incentives invest less in innovation, employee development, and infrastructure. + +**Thaler et al. (1997):** People given frequent performance feedback (analogous to frequent reward cycles) take fewer risks and make worse long-term decisions than those given infrequent feedback. This is called **myopic loss aversion**. + +### Product Implications + +| Short-Term Incentive | Short-Term Behavior | Long-Term Cost | +|---------------------|---------------------|----------------| +| Daily login rewards | Users login but don't engage | No habit formation; users leave when rewards stop | +| Flash sale urgency | Users buy impulsively | Increased returns; reduced brand trust | +| Monthly usage targets | Users binge at month-end | No sustainable workflow adoption | + +## When Extrinsic Rewards DO Work + +Rewards are not universally harmful. They work well for **algorithmic tasks** -- tasks with a clear set of steps and a known solution. + +### Algorithmic vs. Heuristic Tasks + +| Task Type | Description | Reward Effect | Examples | +|-----------|-------------|---------------|----------| +| **Algorithmic** | Clear steps, known solution | Rewards improve speed and output | Data entry, assembly, form filling | +| **Heuristic** | No clear path, requires exploration | Rewards hurt performance | Design, strategy, writing, coding | + +### Conditions Where Rewards Help + +- The task is genuinely boring and has no intrinsic motivation +- The task requires no creative thinking +- The reward acknowledges that the task is dull ("I know this isn't exciting, but...") +- There is no existing intrinsic motivation to undermine + +## "If-Then" vs. "Now-That" Rewards + +This distinction is the most actionable takeaway for reward design. + +### Comparison + +| Dimension | "If-Then" Reward | "Now-That" Reward | +|-----------|-----------------|-------------------| +| **Timing** | Announced before the task | Given after the task | +| **Expectation** | Expected, contingent | Unexpected, non-contingent | +| **Framing** | "If you do X, you get Y" | "Now that you did X, here's Y" | +| **Motivation impact** | Undermines intrinsic motivation | Minimal impact on intrinsic motivation | +| **Example (product)** | "Complete 5 lessons to earn a badge" | "You completed 5 lessons! Here's something special." | +| **Example (team)** | "Hit quota, get bonus" | "Your work this quarter was outstanding -- here's a bonus" | + +### Why "Now-That" Works Better + +- No prior expectation means no cognitive reframing of the task +- The reward feels like recognition, not payment +- The person doesn't optimize for the reward during the task +- Caution: if "now-that" rewards become predictable, they convert to "if-then" rewards + +## Reward Design Guidelines + +When rewards are genuinely necessary, follow these principles to minimize damage. + +### Checklist for Necessary Reward Systems + +- [ ] The task is primarily algorithmic (clear steps, little creativity required) +- [ ] There is minimal existing intrinsic motivation to undermine +- [ ] The reward acknowledges the routine nature of the task +- [ ] The reward is offered with maximum autonomy in how to complete the task +- [ ] The reward is non-controlling (no surveillance or micromanagement attached) +- [ ] The reward provides useful information about competence (feedback, not just payment) +- [ ] The reward is fair relative to the effort (unfair rewards are worse than no reward) +- [ ] "Now-that" is preferred over "if-then" wherever possible +- [ ] The reward doesn't create a single metric that invites gaming + +### Reward Escalation Prevention + +| Strategy | How It Works | +|----------|-------------| +| Vary reward type | Alternate between recognition, autonomy grants, learning opportunities | +| Keep rewards unexpected | Surprise recognition prevents entitlement cycles | +| Tie rewards to effort, not outcome | "You worked hard on this" vs. "You hit the number" | +| Use non-tangible rewards | Autonomy, choice, praise, and feedback resist habituation | +| Cap reward frequency | Monthly or quarterly instead of daily prevents rapid escalation | + +## Common Reward System Mistakes in Products and Teams + +### Product Mistakes + +| Mistake | Why It Fails | Better Approach | +|---------|-------------|-----------------| +| Points for every action | Devalues meaningful progress | Reserve recognition for genuine milestones | +| Leaderboards showing top 10 | Discourages 99% of users | Show personal progress or nearby peers | +| Time-limited rewards | Creates anxiety, not engagement | Celebrate completion regardless of timing | +| Removing earned rewards | Feels punishing, erodes trust | Rewards once earned should persist | +| Identical rewards for all | No autonomy, no personal meaning | Let users choose their reward type | + +### Team Mistakes + +| Mistake | Why It Fails | Better Approach | +|---------|-------------|-----------------| +| Stack-ranking with bonuses | Pits team members against each other | Team-based recognition | +| Individual commissions only | Discourages collaboration | Mix individual and team incentives | +| Surprise metric changes | Destroys trust in the system | Stable, transparent criteria | +| Paying for hours, not output | Rewards presence over productivity | Focus on outcomes and autonomy | +| Annual reviews tied to ratings | Once-a-year feedback cycle | Continuous, informal feedback | + +### Self-Assessment: Is Your Reward System Helping or Hurting? + +| Question | Yes = Risk | Action | +|----------|-----------|--------| +| Do users/employees work only when rewarded? | Intrinsic motivation is gone | Rebuild intrinsic drivers before adding rewards | +| Are people gaming the metrics? | Reward is misaligned | Redesign metrics or remove contingent rewards | +| Do people expect bigger rewards each cycle? | Addiction pattern | Shift to non-tangible, variable recognition | +| Did engagement drop after changing rewards? | Reward dependency | Gradually transition to intrinsic motivation design | +| Are people doing the minimum to qualify? | No intrinsic interest | The task may need redesign, not better rewards | diff --git a/.agents/skills/drive-motivation/references/mastery.md b/.agents/skills/drive-motivation/references/mastery.md new file mode 100644 index 00000000..4114b1c4 --- /dev/null +++ b/.agents/skills/drive-motivation/references/mastery.md @@ -0,0 +1,259 @@ +# Mastery: The Desire to Get Better at Something That Matters + +Mastery -- the urge to improve, to develop skill, to feel competent -- is one of the most powerful forces in human motivation. Unlike extrinsic rewards that diminish over time, the pursuit of mastery is self-renewing: the better you get, the more you want to get better. This reference provides a deep dive into the three laws of mastery, the science of flow states, deliberate practice principles, and actionable patterns for designing mastery into products and teams. + +## Three Laws of Mastery + +### Law 1: Mastery Is a Mindset + +Mastery begins with how you think about ability itself. Carol Dweck's research at Stanford identifies two mindsets that determine whether people pursue mastery or avoid it. + +| Dimension | Fixed Mindset | Growth Mindset | +|-----------|--------------|----------------| +| **Core belief** | Ability is innate and static | Ability is developed through effort | +| **Response to challenge** | Avoidance (might reveal inadequacy) | Embrace (opportunity to grow) | +| **Response to failure** | Devastation, shame | Learning, adjustment | +| **Response to effort** | "If I have to try hard, I must not be good" | "Effort is the path to mastery" | +| **Response to criticism** | Defensive, dismissive | Reflective, integrative | +| **Response to others' success** | Threatened | Inspired | + +**Key finding (Dweck, 2006):** Simply telling students that intelligence is malleable (growth mindset intervention) improved their performance significantly compared to a control group. The mindset shift preceded the behavioral change. + +**Design implication:** Products and teams should frame every signal in growth terms. + +| Fixed Mindset Signal | Growth Mindset Signal | +|---------------------|----------------------| +| "You failed" | "You haven't mastered this yet" | +| "Score: 60/100" | "You've improved 15 points since last week" | +| "Wrong answer" | "Try a different approach" | +| Performance ranking | Personal progress tracking | +| "You're a natural" | "Your practice is paying off" | + +### Law 2: Mastery Is a Pain + +Mastery requires sustained effort through what Anders Ericsson calls **deliberate practice** -- focused, structured, effortful work at the edge of current ability. It is not inherently enjoyable in the moment, but it produces a deep satisfaction that passive entertainment never can. + +**The paradox:** The activities that lead to mastery often feel uncomfortable while you're doing them. The reward comes from looking back and seeing how far you've come. + +**Deliberate practice principles (Ericsson & Pool, 2016):** + +1. **Focused attention:** Full concentration on the specific skill being developed +2. **Just beyond current ability:** Practice in the zone where failure is frequent but not overwhelming +3. **Immediate feedback:** Know whether you succeeded or failed right away +4. **Repetition with variation:** Repeat the skill, but vary the conditions +5. **Expert guidance:** A coach or system that identifies specific weaknesses + +**This is where flow states emerge.** When challenge and skill are balanced at the edge of ability, and feedback is immediate, people enter the optimal experience state that Csikszentmihalyi documented. + +### Law 3: Mastery Is Asymptotic + +You can approach mastery but never fully reach it. Like an asymptote in mathematics, you get closer and closer but never arrive. + +**Why this matters:** If mastery were achievable, people would stop once they reached it. Because it's asymptotic, the pursuit itself becomes the source of satisfaction. There is always a next level, a refinement, a deeper understanding. + +**Design implication:** Never create a "you've mastered everything" endpoint. Always reveal the next horizon. + +| Anti-Pattern | Why It Fails | Better Design | +|-------------|-------------|---------------| +| "100% complete" with nothing beyond | User has nowhere to go | Reveal advanced challenges or new dimensions | +| Level cap with no endgame | Mastery pursuit ends abruptly | Prestige levels, new skill trees, community challenges | +| "Expert" badge as terminal state | Implies nothing left to learn | "Expert" unlocks mentor role or harder content | + +## Flow State: Csikszentmihalyi's Conditions + +Mihaly Csikszentmihalyi identified flow as the optimal psychological state where people are fully absorbed in an activity. It is the experiential manifestation of mastery pursuit. + +### The Eight Conditions of Flow + +| Condition | Description | Design Application | +|-----------|-------------|-------------------| +| **Clear goals** | Know exactly what you're trying to achieve | Explicit objectives for every task | +| **Immediate feedback** | Know instantly whether you're succeeding | Real-time signals (visual, auditory, haptic) | +| **Challenge-skill balance** | Task difficulty matches current ability | Adaptive difficulty systems | +| **Concentration** | Deep focus without interruption | Minimize notifications during active tasks | +| **Loss of self-consciousness** | Too absorbed to worry about judgment | Remove social comparison during focused work | +| **Sense of control** | Feel capable of influencing the outcome | User agency over the task | +| **Transformation of time** | Hours feel like minutes | Don't interrupt with unnecessary time markers | +| **Autotelic experience** | The activity is intrinsically rewarding | The doing is the reward | + +### The Flow Channel + +The relationship between challenge level and skill level determines the user's psychological state. + +``` +Challenge +Level + High | ANXIETY | AROUSAL | FLOW + | | | + Med | WORRY | CONTROL | FLOW + | | | + Low | APATHY | BOREDOM | RELAXATION + |_______________|______________|_______________ + Low Medium High + Skill Level +``` + +**The goal:** Keep users in the FLOW channel by progressively increasing challenge as skill grows. If a user is anxious, reduce difficulty. If bored, increase it. + +### Flow Disruptors + +Patterns that break flow state and should be avoided during focused activities. + +| Disruptor | Example | Solution | +|-----------|---------|----------| +| Unexpected popups | "Rate this app!" during active use | Queue non-urgent prompts for natural break points | +| Social notifications | "Your friend just posted!" during work | DND mode during focused tasks | +| Ads or interruptions | Banner ads during gameplay or learning | Ad-free zones during flow activities | +| Forced waiting | Loading screens, cooldown timers | Preload content, eliminate artificial gates | +| Context switching | Navigating away for a sub-task | Keep all needed tools in-context | + +## Deliberate Practice in Product Design + +Products can structure experiences that mirror deliberate practice principles. + +| Principle | Product Pattern | Example | +|-----------|----------------|---------| +| **Focused attention** | Single-task mode, distraction blocking | Forest app blocks phone use during focus sessions | +| **Edge of ability** | Adaptive difficulty that adjusts to performance | Duolingo adjusts question difficulty based on recent accuracy | +| **Immediate feedback** | Real-time response to user actions | Grammarly highlights errors as you type | +| **Repetition with variation** | Spaced repetition with varied context | Anki flashcards: same concept, different angles | +| **Expert guidance** | AI-powered coaching, curated feedback | GitHub Copilot suggests improvements in real-time | + +## Mastery in Product Design + +### Progress Systems That Work + +Progress visibility is essential for mastery motivation. Users need to see where they've been, where they are, and where they're going. + +| Pattern | Description | Example | +|---------|-------------|---------| +| **Skill trees** | Visual map of abilities and their relationships | Codecademy learning paths | +| **Progress bars** | Linear completion tracking | LinkedIn profile strength meter | +| **Contribution graphs** | Heat maps of activity over time | GitHub contribution graph | +| **Before/after comparisons** | Show the user's past self vs. present self | Language learning: compare day-1 recording to day-60 | +| **Milestone celebrations** | Mark significant achievements | Fitbit: vibration and animation at 10,000 steps | +| **Streak tracking** | Consecutive days of practice | Duolingo streaks (note: can shift to extrinsic if overemphasized) | + +### Adaptive Difficulty Design + +Matching challenge to skill is the single most important mastery design principle. + +| User Signal | Interpretation | System Response | +|------------|---------------|-----------------| +| Completing tasks too quickly | Challenge too low | Increase difficulty, skip ahead | +| Completing tasks with high accuracy | Nearing mastery of current level | Introduce next-level content | +| Failing repeatedly | Challenge too high | Reduce difficulty, offer hints | +| Long pauses between actions | Confusion or frustration | Provide contextual help | +| Voluntary engagement with harder content | Seeking challenge | Unlock advanced options | + +### Feedback Loop Design + +Effective feedback for mastery has specific characteristics. + +| Characteristic | Description | Anti-Pattern | +|---------------|-------------|-------------| +| **Immediate** | Happens within seconds of the action | Delayed reports (weekly summaries) | +| **Specific** | Tells you exactly what to adjust | Generic "good job" or "try again" | +| **Actionable** | Suggests a concrete next step | Vague advice ("be more creative") | +| **Non-judgmental** | Focuses on the work, not the person | "You're bad at this" | +| **Comparative to self** | Shows improvement over your own baseline | Comparison only to others | +| **Calibrated** | Level of detail matches user's experience | Expert-level feedback for beginners | + +## Mastery in Teams + +### Creating a Mastery Culture + +| Practice | Description | Implementation | +|----------|-------------|---------------| +| **Stretch goals** | Assignments that push beyond current comfort zone | 70-20-10 rule: 70% current skill, 20% stretch, 10% brand new | +| **Learning budgets** | Dedicated money and time for skill development | $1,000-$5,000/year per person for courses, conferences, books | +| **Internal teaching** | Team members teach each other | Lunch-and-learn sessions, internal tech talks | +| **Failure reviews** | Analyze what went wrong without blame | Blameless post-mortems (Etsy, Google model) | +| **Skill mapping** | Visible competency matrices | Team skill radar charts, updated quarterly | +| **Mentorship programs** | Pair experienced practitioners with learners | Self-selected mentorship (not assigned) | + +### Goldilocks Tasks + +The most engaging tasks are "Goldilocks tasks" -- not too hard, not too easy. + +**Framework for task assignment:** + +``` +Too Easy (Boredom) Goldilocks Zone (Flow) Too Hard (Anxiety) +|__________________________|_____________________________|________________________| +- Repetitive tasks - Familiar with one new - Multiple unknown + below skill level element variables +- No learning required - Clear goal, uncertain path - No relevant experience +- Already mastered - Achievable with full effort - No support available +- "I could do this in - "I'll need to figure - "I have no idea where + my sleep" this out" to start" +``` + +**Manager's role:** Continuously adjust task difficulty as team members grow. What was a Goldilocks task six months ago may now be too easy. + +## Progress Visualization Patterns + +### Effective Progress Indicators + +| Type | Best For | Example | +|------|----------|---------| +| **Linear progress bar** | Tasks with clear completion criteria | Course completion: 7 of 12 modules | +| **Radial/circular progress** | Recurring goals or habits | Activity rings (Apple Watch) | +| **Heat map** | Consistency tracking over time | GitHub contribution graph | +| **Skill radar chart** | Multi-dimensional skill development | RPG character stats applied to real skills | +| **Before/after timeline** | Showing improvement over time | Writing quality comparison: first draft vs. tenth | +| **Level indicators** | Gamified skill tiers | Stack Overflow reputation and badges | +| **Micro-progress signals** | Within-task feedback | Typing speed indicator during a lesson | + +### Progress Visualization Anti-Patterns + +| Anti-Pattern | Why It Fails | Fix | +|-------------|-------------|-----| +| Progress only relative to others | Discourages most users | Show personal progress first | +| All-or-nothing completion | No credit for partial progress | Granular sub-task tracking | +| Hidden progress | Users can't see their growth | Make progress visible by default | +| Vanity metrics | Numbers that don't reflect real skill | Tie metrics to actual competence | +| Resetting progress | Losing accumulated achievement | Progress should only grow | + +## Mastery Audit Checklist + +### Progress Visibility + +- [ ] Users can see their current skill level or progress +- [ ] Progress is tracked over time (not just current state) +- [ ] Milestones and achievements mark significant progress points +- [ ] Users can compare their current self to their past self +- [ ] Progress indicators are tied to meaningful skill development, not vanity metrics + +### Adaptive Challenge + +- [ ] The product adjusts difficulty based on user performance +- [ ] Users who are struggling receive easier tasks or additional support +- [ ] Users who are excelling are offered greater challenges +- [ ] There is always a "next level" or new dimension to explore +- [ ] The difficulty curve is gradual, not sudden + +### Feedback Quality + +- [ ] Feedback is immediate (within seconds of the action) +- [ ] Feedback is specific (identifies exactly what to improve) +- [ ] Feedback is actionable (suggests a concrete next step) +- [ ] Feedback is framed in growth terms ("not yet" rather than "wrong") +- [ ] Feedback comes at appropriate frequency (not too sparse, not overwhelming) + +### Flow Support + +- [ ] Clear goals exist for every activity +- [ ] Distractions are minimized during focused tasks +- [ ] The challenge-skill balance is maintained +- [ ] Users feel a sense of control over the outcome +- [ ] Natural break points exist (not artificial interruptions) + +### Team Mastery + +- [ ] Team members have access to learning resources and budgets +- [ ] Stretch assignments are available for those ready for them +- [ ] Failure is treated as a learning opportunity +- [ ] Internal knowledge sharing is encouraged and facilitated +- [ ] Skill development is part of performance conversations +- [ ] Mentorship relationships exist and are supported diff --git a/.agents/skills/drive-motivation/references/purpose.md b/.agents/skills/drive-motivation/references/purpose.md new file mode 100644 index 00000000..114b3b73 --- /dev/null +++ b/.agents/skills/drive-motivation/references/purpose.md @@ -0,0 +1,273 @@ +# Purpose: The Yearning to Serve Something Larger Than Ourselves + +Purpose is the context that gives autonomy direction and mastery meaning. Without purpose, autonomy becomes aimless freedom and mastery becomes hollow skill-building. When people connect their actions to something they care about beyond themselves -- a mission, a community, a cause -- motivation becomes self-sustaining and resilient. This reference provides frameworks for building purpose into products, teams, and organizations. + +## Three Expressions of Purpose + +Daniel Pink identifies three ways that purpose manifests in organizations and products. Authentic purpose requires alignment across all three. + +### Purpose Goals + +What the organization or product is trying to achieve beyond profit. + +| Weak Purpose Goal | Strong Purpose Goal | +|-------------------|---------------------| +| "Increase shareholder value" | "Organize the world's information and make it universally accessible" (Google) | +| "Be the market leader" | "Accelerate the world's transition to sustainable energy" (Tesla) | +| "Maximize revenue" | "Give people the power to build community and bring the world closer together" (Meta) | +| "Grow user base" | "To plant 1 billion trees by making search sustainable" (Ecosia) | + +**Key test:** Would this goal still matter even if the organization didn't profit from it? If yes, it's a genuine purpose goal. + +### Purpose Words + +The language an organization uses reveals whether it operates from purpose or profit. + +| Profit-Oriented Language | Purpose-Oriented Language | +|--------------------------|--------------------------| +| Users / consumers | Members / community / people | +| Employees / headcount | Team members / associates / colleagues | +| Revenue targets | Impact goals | +| Market share | People served | +| User acquisition | Community growth | +| Monetization | Value creation | +| Engagement metrics | Meaningful interactions | +| Churn rate | People we lost (and why) | + +**Why words matter:** Language shapes thinking. When a company calls people "users," it frames them as resources to be consumed. When it calls them "community members," it frames the relationship as reciprocal. The words you choose internally shape the culture and decisions externally. + +### Purpose Policies + +Actions and policies that demonstrate purpose is real, not just rhetoric. + +| Company | Purpose Policy | Why It's Credible | +|---------|---------------|-------------------| +| Patagonia | "Don't Buy This Jacket" campaign | Actively discouraged consumption during peak sales | +| REI | #OptOutside (closed on Black Friday) | Sacrificed the biggest retail sales day of the year | +| Costco | Pays above-market wages with full benefits | Reduced profit margin to honor employee commitment | +| Salesforce | 1-1-1 model (1% equity, 1% product, 1% time to charity) | Baked into corporate structure from founding | +| Buffer | Full salary and equity transparency | Published all salaries publicly | + +**Key test:** Does the policy cost the organization something? Purpose policies that are free or profitable aren't credible signals. + +## Purpose-Driven Product Design + +### Making Impact Visible + +The most effective purpose-driven design makes the user's positive impact tangible and specific. + +| Pattern | How It Works | Example | +|---------|-------------|---------| +| **Impact counter** | Running total of user's contribution | Wikipedia: "Your edits have been viewed X times" | +| **Specific attribution** | Show exactly where impact landed | Charity: Water shows GPS coordinates of funded wells | +| **Aggregate impact** | Show collective community achievement | Ecosia: "Our community has planted 200M+ trees" | +| **Before/after** | Visualize the change created | DonorsChoose: photos from classrooms funded | +| **Progress toward goal** | Show contribution to a larger objective | Kickstarter: funding progress bar | +| **Impact stories** | Narratives of real people affected | Kiva: stories from loan recipients | + +### Connecting Individual Actions to Collective Impact + +Users are more motivated when they can see how their small action contributes to a larger outcome. + +| User Action | Individual Frame (Weak) | Collective Frame (Strong) | +|------------|------------------------|--------------------------| +| Using a search engine | "You searched the web" | "Your searches helped plant 47 trees this month" (Ecosia) | +| Writing a review | "You wrote a review" | "Reviews like yours helped 1,200 people make better decisions this week" | +| Completing a workout | "You burned 300 calories" | "Our community ran the equivalent of Earth to Moon this month" (Strava) | +| Answering a question | "You answered a question" | "Your answer was viewed 5,000 times and helped 200 people" (Stack Overflow) | +| Making a purchase | "Order confirmed" | "With this purchase, a meal was provided to a child in need" (TOMS) | + +### Building Purpose into Features + +| Feature Area | Without Purpose | With Purpose | +|-------------|----------------|--------------| +| **Onboarding** | "Here's how the app works" | "Here's why this app exists and what we're building together" | +| **Empty states** | "No data yet" | "Start contributing to [mission] by [first action]" | +| **Milestones** | "You've used the app 100 times" | "You've helped 100 people through your contributions" | +| **Notifications** | "Come back! You haven't logged in" | "Your community needs you: 5 questions await your expertise" | +| **Settings** | "Manage your preferences" | "Choose how you want to make a difference" | +| **Cancellation** | "Are you sure? You'll lose your data" | "You've helped X people. Here's what you'll miss." | + +## Purpose in Organizations + +### Beyond Profit Maximization + +Pink argues that the most motivated organizations treat profit as a necessary condition (fuel for the purpose), not the purpose itself. + +**The purpose spectrum:** + +| Level | Orientation | Example | +|-------|-----------|---------| +| **1. Profit only** | "We exist to make money" | Most publicly traded companies (stated or unstated) | +| **2. Profit + social responsibility** | "We make money and give some back" | Corporate CSR programs | +| **3. Purpose with profit** | "We exist for a purpose and sustain it through profit" | Patagonia, Ecosia | +| **4. Purpose first** | "Our purpose comes first; we figure out sustainability" | Wikipedia, many nonprofits | + +**Finding the balance:** Level 3 is the most sustainable for most organizations. Pure purpose (level 4) struggles with sustainability. Pure profit (level 1) struggles with motivation and talent retention. + +### Purpose-Driven Messaging That Resonates + +| Principle | Description | Example | +|-----------|-------------|---------| +| **Specific, not vague** | Concrete impact, not abstract values | "We've provided clean water to 15 million people" vs. "We care about the environment" | +| **Verifiable, not claimed** | Show evidence, not assertions | Published impact reports with third-party verification | +| **Costly, not free** | Purpose requires sacrifice to be credible | "We turned down a $10M contract because it conflicted with our mission" | +| **Consistent, not occasional** | Integrated into daily operations, not annual events | Everyday decisions reflect purpose, not just PR moments | +| **User-centered, not company-centered** | Frame purpose in terms of what the user contributes | "You helped plant 47 trees" vs. "We planted 1M trees" | + +## Purpose Audit for Products + +### Mission Clarity + +- [ ] The product has a stated mission beyond "make money" or "grow users" +- [ ] The mission is visible to users (not buried in an About page) +- [ ] New features are evaluated against the mission (not just revenue impact) +- [ ] The mission is specific enough to guide decisions + +### Impact Visibility + +- [ ] Users can see the impact of their actions +- [ ] Impact is specific and concrete (numbers, stories, locations) +- [ ] Aggregate community impact is visible +- [ ] Impact data is updated in real-time or near real-time +- [ ] Milestones celebrate meaningful impact, not vanity metrics + +### Community Connection + +- [ ] Users feel part of something bigger than individual use +- [ ] There are shared goals that the community works toward +- [ ] Users can see other people's contributions and impact +- [ ] The product facilitates genuine human connection +- [ ] Community achievements are celebrated collectively + +### Values Alignment + +- [ ] The product's business model aligns with its stated purpose +- [ ] The company's actions match its words (no purpose-washing) +- [ ] Users trust that the company means what it says +- [ ] Difficult decisions are made in favor of purpose over short-term profit + +## Purpose Audit for Teams and Organizations + +### Leadership + +- [ ] Leaders regularly articulate why the work matters +- [ ] Strategic decisions are explained in terms of purpose, not just profit +- [ ] Leaders model purpose-driven behavior (not just talk about it) +- [ ] Purpose is part of hiring conversations and criteria + +### Culture + +- [ ] Team members can articulate why their work matters +- [ ] Individual contributions are connected to organizational impact +- [ ] Purpose is discussed in team meetings and retrospectives +- [ ] The organization's language reflects purpose (see Purpose Words above) + +### Policies + +- [ ] At least one policy demonstrates purpose at a cost to profit +- [ ] Compensation and incentives align with purpose goals +- [ ] The organization measures impact, not just financial performance +- [ ] Purpose is part of the performance review conversation + +## Real-World Purpose Examples + +### Patagonia + +**Mission:** "We're in business to save our home planet." + +**Purpose actions:** +- "Don't Buy This Jacket" campaign actively discouraged consumption +- Donates 1% of sales to environmental causes (1% for the Planet) +- Worn Wear program repairs and resells used clothing +- Sued the federal government to protect public lands +- Founder transferred ownership to a trust dedicated to fighting climate change + +**Why it works:** Every action costs the company something. The purpose is embedded in the business model, not layered on top. + +### TOMS + +**Original model:** Buy one pair of shoes, TOMS gives one pair to a child in need. + +**Evolution:** Shifted from one-for-one to investing 1/3 of profits in grassroots good, including community organizations. + +**Lesson:** The original model was powerful for purpose-driven messaging but faced criticism about dependency and undermining local economies. TOMS evolved, demonstrating that purpose models must adapt. + +### Wikipedia + +**Mission:** "Imagine a world in which every single person on the planet is given free access to the sum of all human knowledge." + +**Purpose mechanics:** +- Entirely volunteer-written (no payment, pure purpose) +- Transparent editing history (every contribution visible) +- Annual donation campaigns emphasize mission, not features +- No advertising (purpose over revenue) + +**Why it works:** Contributors edit because they believe in the mission. There is no extrinsic reward for editing Wikipedia. The intrinsic satisfaction of contributing to human knowledge drives millions of edits per month. + +### Charity: Water + +**Mission:** Bring clean and safe drinking water to every person on the planet. + +**Purpose mechanics:** +- 100% of public donations go to projects (operating costs funded separately) +- GPS coordinates published for every funded well +- Photos and completion reports for every project +- Donors can see exactly where their money went + +**Why it works:** Radical transparency removes skepticism. When donors see the exact well their money funded, purpose becomes tangible. + +### Ecosia + +**Mission:** Use search engine profits to plant trees. + +**Purpose mechanics:** +- Counter shows total trees planted (200M+) +- Personal counter shows each user's contribution +- Financial reports published monthly +- Runs on renewable energy + +**Why it works:** Every search feels like a micro-contribution. The counter makes the abstract ("I used a search engine") into the concrete ("I helped plant a tree"). + +## Purpose vs. Purpose-Washing: Authenticity Matters + +### Red Flags of Purpose-Washing + +| Signal | What It Looks Like | Why It Fails | +|--------|-------------------|-------------| +| **Purpose without cost** | "We care about X" but take no costly action | Users see through cheap talk | +| **Purpose as marketing** | Purpose campaign during PR crisis | Perceived as manipulative | +| **Selective purpose** | Ethical in one area, exploitative in another | Inconsistency destroys credibility | +| **Vague purpose** | "Making the world a better place" | Too abstract to be meaningful or verifiable | +| **Purpose that contradicts business model** | "We value your privacy" from a surveillance company | Actions speak louder than statements | +| **Purpose that appears only after scandal** | "We've always cared about X" after a public incident | Reactive purpose is transparent damage control | + +### Authenticity Checklist + +- [ ] The purpose existed before it was publicly communicated +- [ ] The purpose has cost the organization something tangible +- [ ] Leadership makes decisions that favor purpose over short-term profit +- [ ] Employees believe the purpose is genuine (check internal surveys) +- [ ] External observers (media, users, partners) validate the purpose claim + +## Measuring Purpose Engagement + +### For Products + +| Metric | What It Measures | How to Track | +|--------|-----------------|-------------| +| **Mission awareness** | Do users know the product's purpose? | Survey: "In your words, what is [product]'s mission?" | +| **Impact engagement** | Do users interact with impact features? | Click-through on impact dashboards, donation flows | +| **Purpose-driven retention** | Do purpose-aware users retain better? | Cohort analysis: users who engaged with purpose content vs. those who didn't | +| **Word of mouth** | Do users recommend because of purpose? | NPS follow-up: "Why did you recommend us?" | +| **Willingness to pay** | Do users pay more for purpose-aligned products? | Price sensitivity testing among purpose-aware segments | + +### For Teams + +| Metric | What It Measures | How to Track | +|--------|-----------------|-------------| +| **Mission articulation** | Can team members explain why the work matters? | Ask in 1:1s or anonymous surveys | +| **Discretionary effort** | Do people go beyond minimum requirements? | Manager observation, project quality metrics | +| **Retention** | Do purpose-connected employees stay longer? | Turnover analysis by engagement scores | +| **Recruitment** | Does purpose attract candidates? | Ask in interviews: "Why do you want to work here?" | +| **Decision quality** | Do teams reference purpose in decision-making? | Observe meeting discussions, decision documentation | diff --git a/.agents/skills/drive-motivation/references/type-i.md b/.agents/skills/drive-motivation/references/type-i.md new file mode 100644 index 00000000..6ffe4a7e --- /dev/null +++ b/.agents/skills/drive-motivation/references/type-i.md @@ -0,0 +1,283 @@ +# Type I vs. Type X: Intrinsic and Extrinsic Behavioral Styles + +Daniel Pink distinguishes between two behavioral types that describe how people relate to motivation. Type X (extrinsic) behavior is fueled by external rewards -- money, status, praise, grades. Type I (intrinsic) behavior is fueled by the inherent satisfaction of the activity itself -- autonomy, mastery, purpose. Understanding this distinction is essential for designing products, teams, and cultures that cultivate lasting motivation. + +## Type I and Type X: Detailed Comparison + +| Dimension | Type X (Extrinsic) | Type I (Intrinsic) | +|-----------|---------------------|---------------------| +| **Primary fuel** | External rewards and recognition | Internal satisfaction and growth | +| **Relationship to effort** | Effort is a cost to be minimized | Effort is the path to improvement | +| **Time horizon** | Short-term (next reward cycle) | Long-term (sustained growth) | +| **Relationship to goals** | Goals set by others; optimize for metric | Self-set goals; optimize for learning | +| **Response to failure** | Avoidance, shame, blame | Analysis, adjustment, persistence | +| **Response to challenge** | Threat (might not get the reward) | Opportunity (chance to grow) | +| **Relationship to money** | Money is the primary motivator | Money is necessary but not sufficient | +| **Sustainability** | Depletes over time (hedonic adaptation) | Renews over time (compound growth) | +| **Social comparison** | Constant (am I ahead of others?) | Occasional (am I ahead of my past self?) | +| **Creative output** | Safe, conventional, reward-optimized | Experimental, exploratory, interest-driven | +| **Mindset** | Tends toward fixed mindset | Tends toward growth mindset | +| **Well-being** | Lower life satisfaction, higher stress | Higher life satisfaction, lower burnout | + +## Characteristics of Type I Behavior + +### What Type I Is + +- **Self-directed:** Type I individuals set their own goals and define their own success criteria +- **Mastery-oriented:** They pursue improvement for its own sake, not for external validation +- **Purpose-connected:** They care about why they're doing something, not just what they get for it +- **Resilient:** Setbacks are data points for adjustment, not reasons to quit +- **Long-term focused:** Willing to sacrifice short-term rewards for long-term growth +- **Intrinsically curious:** Ask "why" and "what if" rather than "what's in it for me" + +### What Type I Is Not + +| Misconception | Reality | +|--------------|---------| +| "Type I people don't care about money" | They care about fair compensation; they just don't need it as primary motivation | +| "Type I people are always happy" | They experience frustration, especially when autonomy is restricted | +| "Type I is a personality trait" | It's a behavioral style that can be cultivated | +| "Type I people are lone wolves" | Many are deeply collaborative, driven by shared purpose | +| "Type I means no ambition" | Type I individuals are often highly ambitious -- about mastery and impact, not status | + +### The Renewable Resource Advantage + +Type X motivation depletes: you need bigger rewards, more recognition, higher status just to maintain the same level of engagement. Type I motivation compounds: the better you get, the more interesting the work becomes, and the more motivated you are to continue. + +| Year | Type X Engagement | Type I Engagement | +|------|------------------|-------------------| +| 1 | High (new rewards are exciting) | Moderate (still learning the domain) | +| 2 | Moderate (same rewards feel smaller) | Growing (skills unlock new challenges) | +| 3 | Low (reward fatigue, looking elsewhere) | High (deep competence, flow states frequent) | +| 5 | Disengaged or gone (unless rewards escalate) | Peak (mastery pursuit is deeply satisfying) | +| 10 | Burnout (if still relying on external fuel) | Sustained (purpose and mastery continue to deepen) | + +## Type I Is Made, Not Born + +This is the most actionable insight in Drive: Type I behavior is not an innate personality trait. It's a set of behaviors that can be cultivated through environment design. + +### The Evidence + +**Deci & Ryan's Self-Determination Theory** demonstrates that when environments support autonomy, competence, and relatedness, people naturally move toward intrinsic motivation. When environments are controlling, people move toward extrinsic motivation. + +**Dweck's Mindset Research** shows that a growth mindset (the foundation of Type I) can be developed through targeted interventions. Students told that intelligence is malleable improved performance compared to control groups. + +**Pink's conclusion:** Organizations and products don't find Type I people -- they create the conditions where Type I behavior emerges. + +### The Shift Sequence + +``` +1. Remove controlling elements → Reduce Type X triggers +2. Ensure baseline fairness → Take money off the table +3. Add autonomy → Give choice and control +4. Enable mastery → Provide challenge and feedback +5. Connect to purpose → Link work to something meaningful +6. Model Type I behavior → Leaders demonstrate intrinsic motivation +``` + +## Cultivating Type I in Product Users + +### Design for Intrinsic Engagement + +| Strategy | How It Works | Product Example | +|----------|-------------|-----------------| +| **Remove extrinsic dependency** | Reduce reliance on points, badges, external rewards | Remove daily login bonuses; make the product inherently valuable | +| **Enable autonomy** | Give users control over their experience | Let users customize dashboards, choose learning paths | +| **Support mastery** | Provide clear progress and adaptive challenge | Show skill growth over time, adjust difficulty | +| **Connect to purpose** | Help users see why the product matters to them | Link activity to personal goals or community impact | +| **Foster curiosity** | Create moments of discovery and surprise | Hidden features, easter eggs, "did you know" moments | +| **Celebrate growth** | Recognize improvement over achievement | "You've improved 40% this month" vs. "Top 10% badge" | + +### User Type I Indicators + +Signs that your users are operating in Type I mode: + +| Indicator | What It Looks Like | +|-----------|-------------------| +| Voluntary exploration | Users try features without being prompted | +| Self-set goals | Users create their own challenges beyond what you designed | +| Community contribution | Users help other users without rewards | +| Feedback volunteering | Users suggest improvements because they care | +| Long sessions | Users spend time because they're absorbed, not obligated | +| Return without prompts | Users come back without notification nudges | +| Creative use | Users use the product in ways you didn't anticipate | + +### User Type X Warning Signs + +Signs that your product is fostering Type X dependency: + +| Warning Sign | What It Means | +|-------------|---------------| +| Users only engage when rewards are active | Intrinsic motivation is absent | +| Usage drops immediately when rewards change | External rewards were the only driver | +| Users game metrics without real engagement | Optimizing for reward, not value | +| Users ask "what do I get?" before trying features | Transactional relationship with the product | +| Users complain rewards are "not enough" | Hedonic adaptation; reward escalation cycle | + +## Cultivating Type I in Team Members + +### Manager Behaviors That Foster Type I + +| Behavior | Why It Works | How to Implement | +|----------|-------------|-----------------| +| **Give context, not commands** | People need to understand "why" to self-direct | Start directives with "Here's why this matters..." | +| **Ask before telling** | Engaging people's thinking builds ownership | "What do you think we should do?" before prescribing | +| **Provide choice** | Even small choices increase autonomy perception | "Would you prefer to tackle A or B first?" | +| **Praise effort, not talent** | Growth mindset framing encourages persistence | "Your preparation really showed" vs. "You're so smart" | +| **Treat failure as data** | Removes fear that kills exploration | "What did we learn?" not "Who's responsible?" | +| **Share the big picture** | Connects daily work to meaningful outcomes | Regular mission-connection in team communication | +| **Remove unnecessary controls** | Surveillance and micromanagement signal distrust | Reduce reporting requirements, status checks | + +### Manager Behaviors That Foster Type X (Avoid These) + +| Behavior | Why It Hurts | What to Do Instead | +|----------|-------------|-------------------| +| Micromanaging process | Strips technique autonomy | Define outcomes, not steps | +| Stack-ranking team members | Creates competition, not collaboration | Evaluate against personal growth | +| Rewarding compliance | Signals that obedience matters more than thinking | Reward initiative and creative problem-solving | +| Using fear of consequences | Triggers defensive behavior | Create psychological safety | +| Ignoring intrinsic motivators | Sends the message that only metrics matter | Ask what energizes people; build on it | +| Over-monitoring hours and activity | Signals distrust | Focus on output and impact | + +## Type I Toolkit + +### Autonomy Audits + +Run quarterly to assess whether your product or team supports autonomy. + +| Area | Question | Score (1-5) | +|------|----------|-------------| +| Task | Can people choose what they work on (at least sometimes)? | ___ | +| Time | Can people choose when they work? | ___ | +| Technique | Can people choose how they approach the work? | ___ | +| Team | Can people choose who they collaborate with? | ___ | +| **Total** | | **/20** | + +**Interpretation:** Below 12 = autonomy-restricted environment. 12-16 = moderate autonomy. 17-20 = autonomy-supportive. + +### Flow Enablement Assessment + +| Condition | Present? | Notes | +|-----------|----------|-------| +| Clear goals for every task | Yes / No | | +| Immediate feedback on performance | Yes / No | | +| Challenge matched to skill level | Yes / No | | +| Minimal interruptions during focused work | Yes / No | | +| Sense of control over the outcome | Yes / No | | + +**Score:** 4-5 "Yes" = flow-supportive. 2-3 = partially supportive. 0-1 = flow-hostile. + +### Purpose Connection Check + +| Question | Answer | +|----------|--------| +| Can every team member articulate why the work matters? | | +| Do team conversations reference impact, not just metrics? | | +| Would team members do this work even if it paid 20% less? | | +| Do people speak proudly about their work outside the office? | | +| Is the organization's mission visible in daily decisions? | | + +## Moving from Type X to Type I: Transition Strategies + +### For Individuals + +| Stage | Action | Duration | +|-------|--------|----------| +| **Awareness** | Recognize extrinsic dependencies (what are you doing only for the reward?) | 1-2 weeks | +| **Baseline** | Ensure financial security (take money off the table) | Ongoing | +| **Experiment** | Try activities purely for interest, with no goal or reward | 2-4 weeks | +| **Reframe** | When catching yourself thinking "what's in it for me," ask "what interests me here?" | Ongoing | +| **Practice** | Deliberately choose challenging tasks that develop skills | Ongoing | +| **Connect** | Link daily activities to personal values and larger purpose | Ongoing | + +### For Organizations + +| Phase | Action | Timeline | +|-------|--------|----------| +| **Assess** | Survey current motivation drivers across the organization | Month 1 | +| **Baseline** | Ensure compensation is fair and competitive (remove money as an issue) | Month 1-3 | +| **Pilot** | Introduce autonomy in one team (FedEx days, flexible hours, ROWE) | Month 2-4 | +| **Learn** | Gather data on engagement, productivity, retention in pilot team | Month 4-6 | +| **Expand** | Roll out autonomy, mastery, and purpose practices to more teams | Month 6-12 | +| **Embed** | Make AMP principles part of hiring, onboarding, and promotion criteria | Month 12+ | + +## Type I Assessment for Individuals + +Rate yourself or team members on each dimension (1 = strongly disagree, 5 = strongly agree). + +| Statement | Score (1-5) | +|-----------|-------------| +| I am driven more by interest in the work than by external rewards | ___ | +| I seek challenges that stretch my abilities | ___ | +| I continue working on problems even when no one is watching | ___ | +| Failure motivates me to try different approaches | ___ | +| I set my own standards rather than relying on others' expectations | ___ | +| I care more about getting better than about being recognized | ___ | +| I can articulate why my work matters beyond the paycheck | ___ | +| I feel energized by difficult work, not drained by it | ___ | +| I am more interested in learning than in proving myself | ___ | +| I would do some version of this work even if I weren't paid for it | ___ | +| **Total** | **/50** | + +**Interpretation:** +- 40-50: Strong Type I orientation +- 25-39: Mixed; context-dependent (common and healthy) +- 10-24: Predominantly Type X; environment may be the cause + +## Organizational Type I Culture Indicators + +### Present in Type I Cultures + +| Indicator | Observable Sign | +|-----------|----------------| +| High voluntary initiative | People start projects without being asked | +| Low voluntary turnover | People stay because they want to, not because they have to | +| Knowledge sharing | People teach each other freely | +| Constructive dissent | People challenge ideas respectfully | +| After-hours passion | People talk about their work enthusiastically outside work | +| Internal mobility | People move between teams to follow interest | +| Experimentation | Failure is discussed openly and without blame | + +### Present in Type X Cultures + +| Indicator | Observable Sign | +|-----------|----------------| +| Clock-watching | People leave at exactly the designated end time | +| Minimal effort | People do the minimum required and no more | +| Information hoarding | Knowledge is power; people don't share | +| Blame culture | Mistakes lead to punishment, not learning | +| Resume-polishing | People optimize for their next job, not current work | +| High attrition | People leave as soon as a better offer appears | +| "Not my job" | People avoid anything outside their defined role | + +## Type I in Hiring and Onboarding + +### Hiring for Type I Orientation + +| Interview Question | Type I Signal | Type X Signal | +|-------------------|--------------|---------------| +| "Why do you want to work here?" | Mission, learning, challenge | Salary, title, brand name | +| "Tell me about a project you're proud of" | Describes growth and learning | Describes recognition and rewards | +| "What do you do outside of work?" | Pursues interests and skills | Focuses on status or consumption | +| "Describe a time you failed" | Describes what they learned | Deflects blame or minimizes | +| "What would you work on if you had total freedom?" | Has a specific, passionate answer | "Whatever the company needs" | + +### Onboarding for Type I Development + +| Week | Type I Onboarding Practice | +|------|---------------------------| +| **Week 1** | Connect new hire to organizational purpose; introduce the "why" before the "how" | +| **Week 2** | Let the new hire choose their first project from a menu of options | +| **Week 3** | Pair with a self-selected mentor; encourage questions and exploration | +| **Week 4** | First solo contribution; provide immediate, growth-oriented feedback | +| **Month 2** | Introduce stretch opportunities; ask what they want to learn | +| **Month 3** | Review: "What's energizing you? What's draining you? How can we adjust?" | + +### Sustaining Type I Over Time + +| Quarter | Practice | +|---------|----------| +| **Q1** | Set personal growth goals alongside team goals | +| **Q2** | FedEx day or hack week -- self-directed project time | +| **Q3** | Skill-swap: teach something you know, learn something new | +| **Q4** | Reflection: "How have I grown this year? What do I want next?" | diff --git a/.agents/skills/good-strategy-bad-strategy/SKILL.md b/.agents/skills/good-strategy-bad-strategy/SKILL.md new file mode 100644 index 00000000..4f01c0c4 --- /dev/null +++ b/.agents/skills/good-strategy-bad-strategy/SKILL.md @@ -0,0 +1,193 @@ +--- +name: good-strategy-bad-strategy +description: 'Formulate and audit real strategy using Richard Rumelt''s "Good Strategy Bad Strategy": an honest diagnosis, a guiding policy, and coherent action instead of goals, vision, and wishful thinking. Use when the user mentions "good strategy bad strategy", "strategy kernel", "diagnosis guiding policy coherent action", "our strategy is just goals", "strategic planning", "mission vs strategy", "annual plan", or "is this actually a strategy". Also trigger when auditing a strategy doc or pitch deck for fluff, turning a goal list into real strategy, formulating strategy for a product or company, or finding leverage and proximate objectives. Covers the kernel of strategy, bad-strategy detection, and sources of power. For product positioning, see obviously-awesome. For uncontested markets, see blue-ocean-strategy.' +license: MIT +metadata: + author: wondelai + version: "1.2.0" +--- + +# Good Strategy Bad Strategy + +A framework for creating and auditing strategy, distilled from Richard Rumelt's *Good Strategy Bad Strategy: The Difference and Why It Matters*. Good strategy has a simple underlying logic — an honest diagnosis of the critical challenge, a guiding policy for overcoming it, and coherent actions that carry the policy out. Use this skill to detect the four hallmarks of bad strategy and to replace goal lists and vision decks with a working kernel. + +## Core Principle + +**Strategy is coherent action backed by an honest diagnosis — not goals, vision, or wishful thinking.** A goal ("20% growth") names an ambition; a strategy explains how the ambition will be achieved given the actual obstacles. Bad strategy is not the absence of strategy but an active substitute for it: buzzword fluff, refusal to name the challenge, and laundry lists of initiatives. The heart of strategy work is choice — concentrating effort and resources on the one or two pivotal objectives whose accomplishment unlocks everything else. + +## Scoring + +**Goal: 10/10.** Score strategies, plans, and strategy documents by walking the eight rows of the Quick Diagnostic and counting how many pass. Report the current score and the specific changes needed to reach 10/10. The bands below name what each tier looks like; the row count keeps the rating reproducible run to run. + +- **9-10 (8 rows pass):** Complete kernel — honest diagnosis, choiceful guiding policy, coordinated resource-backed actions — aimed at a pivot point, with an explicit list of what will not be done +- **7-8 (6-7 pass):** Kernel present but one element weak: thin diagnosis, a policy that rules little out, or actions not yet coordinated and funded +- **5-6 (4-5 pass):** The challenge is named, but the plan is a list of independent initiatives and some goals masquerade as strategy +- **3-4 (2-3 pass):** Mostly goals, targets, and vision statements; no diagnosis; fluff in key passages; nothing ruled out +- **0-2 (0-1 pass):** Pure bad strategy — buzzword fluff, dog's-dinner objective lists, denial of the real challenge + +## Framework + +### 1. The Kernel of Good Strategy + +**Core concept:** Every good strategy shares the same structure: a **diagnosis** that defines and simplifies the critical challenge, a **guiding policy** — the overall approach chosen to overcome the diagnosed obstacles — and **coherent actions**: coordinated, resource-backed steps that carry out the policy. A document missing any of the three is not yet a strategy. + +**Why it works:** A diagnosis replaces the overwhelming complexity of reality with a simpler story that highlights what is critical, often by analogy to a known pattern. The guiding policy channels effort by ruling out vast realms of possible action — like guardrails, it directs without dictating every move. Coherent actions turn intent into coordinated force; most plans fail by jumping straight from ambition to a list of independent initiatives. + +**Key insights:** +- The diagnosis is the strategy's pivot: Gerstner reframed IBM's 1993 challenge from "mainframes are dying, break the company up" to "our advantage is integrated capability; the obstacle is internal coordination" — and everything downstream changed +- A guiding policy is not a goal or a vision — it is an approach ("ride wave X by concentrating on Y"), and a real one feels like a choice with losers +- If a competitor could paste your guiding policy into their deck unchanged, it is a platitude, not a policy +- Coherent actions reinforce one another — each step makes the others easier — and every one carries an owner, resources, and a date +- A kernel needs no mission, vision, or values preamble; it fits on one page +- Most failed "strategies" skip the diagnosis entirely — prescribing before examining + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Annual planning | Kernel before targets | Diagnosis: week-one churn; policy: fastest time-to-value in segment; actions: onboarding rebuild + roadmap cuts | +| Strategy review | Trace each action to the policy | Initiative serving no policy → cut or re-justify | +| Pitch deck | Kernel slide, not goals slide | "The obstacle, our approach, three coordinated moves" | + +**Ethical boundary:** An honest diagnosis names internal causes too — never soften it to protect egos or settle politics. + +See [references/kernel.md](references/kernel.md) when you actually draft a kernel — diagnosis craft, guiding-policy formulation, coherent-action design, a fill-in template, and two worked examples with owners and done-tests. + +### 2. Detecting Bad Strategy + +**Core concept:** Bad strategy is not the absence of strategy — it is its own species with four hallmarks: **fluff** (gibberish masquerading as strategic concepts), **failure to face the challenge**, **mistaking goals for strategy**, and **bad strategic objectives** (dog's-dinner laundry lists or blue-sky impracticalities). + +**Why it works:** Naming the hallmarks turns a vague sense that "this deck says nothing" into specific, fixable findings. Bad strategy persists for identifiable reasons — choice is painful, templates are easy, and positive thinking feels like leadership — so detection must hunt for substitutes for choice, not just bad writing. + +**Key insights:** +- Fluff test: restate the sentence in plain words — "our fundamental strategy is customer-centric intermediation" collapses to "we are a bank," which says nothing +- If the document never names the obstacle, the strategy cannot be evaluated or improved — International Harvester's 1979 plan never mentioned its toxic labor relations, the actual problem +- "20% growth, 20% margin" is a goal; exhortation to push harder is motivation, not a lever — strategy is the lever +- Dog's dinner: a city plan with 47 "strategies" and 178 action items has no strategy; blue-sky: "become the leading platform" restates the end state and skips the how +- Bad strategy has causes: unwillingness to choose (every real choice creates losers — DEC's consensus produced mush), template-style vision-mission-values planning, and New Thought culture (belief that visualizing success produces it) +- The negation test: if the opposite of a statement is absurd ("we will *not* be customer focused"), the statement carries no information + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Strategy deck audit | Score sections against the four hallmarks | "Vision" slide flagged as fluff; no obstacle named anywhere | +| OKR review | Separate ambitions from mechanisms | "Double signups" kept as goal, paired with an explicit how | +| Board update | Demand the challenge slide | "What we're up against" before "what we'll achieve" | + +See [references/bad-strategy.md](references/bad-strategy.md) when auditing a deck or plan — per-hallmark detection checklists, before/after rewrites, why bad strategy proliferates, and a step-by-step deck-audit procedure with a report format. + +### 3. Sources of Power + +**Core concept:** Good strategy applies strength where it has the greatest effect, drawing on recurring sources of power: **leverage** (anticipation, pivot points, concentration), **proximate objectives** (targets close enough to actually hit), **chain-link systems** (quality matched across links), **design** (premeditated, coordinated configuration), **focus**, and **using advantage** (asymmetries protected by isolating mechanisms). + +**Why it works:** Resources are always scarce relative to ambitions. Power comes from asymmetry — knowing something rivals don't, pressing where effort is amplified, or concentrating where they are spread thin. A strategy that names no source of power is hoping effort alone will win, which is matching strength against strength. + +**Key insights:** +- Leverage = anticipation × pivot point × concentration: anticipate predictable behavior, find the point where effort is amplified, then commit past the threshold where results become visible +- A proximate objective is one the team can see how to hit; under high ambiguity, choose closer targets — a JPL engineer made Moon-lander design feasible by simply *deciding* a lunar soil model others could build against +- In chain-link systems, performance is capped by the weakest link — investing in strong links is wasted until the weak one is fixed, which is why such systems stay stuck +- A fully matched chain is also the deepest moat: IKEA's in-house design, flat-pack logistics, and warehouse showrooms each fit the others, so copying one link gains a rival nothing +- Design-type strategy — tight, premeditated coordination of parts — pays when stakes are high and resources scarce; integration buys performance at the cost of flexibility +- An advantage matters only at the point of contention: deepen it, broaden it, or strengthen isolating mechanisms (network effects, brand, patents, tacit know-how) that block imitation + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Startup wedge choice | Concentrate past the threshold | One vertical owned end-to-end, not five touched | +| Stalled growth | Chain-link diagnosis | Fix activation (weakest link) before scaling paid acquisition | +| Ambiguous roadmap | Set a proximate objective | "Ten fintech design partners live" not "be the leader" | + +**Ethical boundary:** Build isolating mechanisms on delivered value — lock-in engineered purely to trap users eventually isolates you from them. + +See [references/sources-of-power.md](references/sources-of-power.md) when choosing where to apply strength — leverage, proximate objectives, chain-link systems, design, focus, and advantage, each with a when-to-use test (unlock test, addressability test, coherence check). + +### 4. Riding Dynamics and Fighting Inertia + +**Core concept:** Waves of change — technology shifts, deregulation, demographic change — are the attacker's best friend: they redistribute advantage and reset rules the incumbents had mastered. Incumbents are held back by three kinds of inertia (routine, culture, proxy) and by entropy — the unmanaged drift into blur and waste. + +**Why it works:** In stable periods incumbents win on scale and accumulated advantage; in transitions their strengths become anchors — they defend legacy margins, rerun obsolete playbooks, and answer to cultures built for the old world. You don't need to predict the future, only to recognize that the present has already changed and act on it before those who can't. + +**Key insights:** +- Guideposts for sensing waves: rising fixed costs (force consolidation), deregulation or rule changes, predictable biases (people extrapolate the present), incumbent response (watch them protect old margins), and attractor states (where the industry "should" land given the technology) +- An attractor state disciplines hype: ask "in the end state, who does the work and who gets paid?" — "all data transport becomes IP" correctly guided Cisco's rise +- Inertia by routine yields to new metrics and outside hires; inertia by culture requires simplification and breaking insulated units; inertia by proxy means the incumbent profits from its *customers'* inertia — banks kept paying low deposit rates because depositors were slow to move +- A rival's inertia is an exploitable asymmetry: attack where responding would force them to break their own economics +- Entropy shows up as blurred product lines, drifting prices, and accidental cross-subsidies — weeding it is real strategy work even with no competitor in sight + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Platform shift | Read the guideposts | Model training costs consolidate; value migrates to workflow owners | +| Pricing attack | Exploit margin defense | Usage-based pricing a seat-license incumbent can't match | +| Mature product | Entropy audit | Three overlapping plans collapsed into one clean ladder | + +**Ethical boundary:** Ride waves by serving the new need better — never by manufacturing fear about the old one. + +See [references/dynamics-inertia.md](references/dynamics-inertia.md) when a market is shifting or an incumbent is stuck — guideposts for spotting waves, diagnosing the three inertia types and entropy, and attacker playbooks for exploiting a rival's inertia. + +### 5. Thinking Like a Strategist + +**Core concept:** A strategy is a hypothesis about what will work, not a deduction from goals. Work like a scientist — diagnose, formulate, test against evidence, revise — and use deliberate techniques (create-destroy, the virtual panel of experts, a written first-person kernel) to defend judgment against first conclusions and herd opinion. + +**Why it works:** The mind grabs the first plausible frame and defends it; groups converge on comfortable consensus. The market is an expensive place to discover you were wrong — cheap, disciplined destruction of your own ideas before commitment buys that learning early. + +**Key insights:** +- Treat strategy as a hypothesis and the market as the lab: Howard Schultz's Italian espresso-bar concept survived because he kept revising it against evidence — dropped the opera music, added chairs, offered nonfat milk +- Create-destroy: generate genuinely different alternatives, then attack your own front-runner as hard as you would attack a rival's plan +- Convene a virtual panel of experts: simulate the specific critiques of people whose judgment you respect — borrowed standards beat solo blind spots +- First conclusions are the enemy; before accepting any diagnosis ask "what else could be going on?" +- Keep the kernel written down — a strategy that lives in your head is unfalsifiable — with the list of what you choose *not* to do beside it +- Independent judgment matters most when the crowd agrees: the market capitalized Global Crossing's hype while the underlying numbers said otherwise + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Quarterly review | Re-test the diagnosis | Churn data contradicts it → kernel revised, not defended | +| Big bet | Create-destroy before commit | A second team builds the case against the acquisition | +| Founder discipline | Written kernel + no-list | One page: diagnosis, policy, three actions, five explicit nots | + +**Ethical boundary:** Use the virtual panel to find flaws, not to stage imagined authority blessing a foregone conclusion. + +See [references/case-studies.md](references/case-studies.md) for fully worked end-to-end examples — a SaaS annual-plan audit, a startup concentration decision, and a vision deck rewritten into a kernel. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Mistaking goals for strategy | "20% growth" names desire, not the lever that produces it | Write the kernel: diagnosis → policy → coherent actions | +| Skipping the diagnosis | Prescribing before examining; plan solves the wrong problem | One-paragraph diagnosis of the critical challenge first | +| Template planning (vision-mission-values) | Fill-in-the-blank boilerplate substitutes for analysis and choice | Start from the obstacle, not the template | +| Fluff in key passages | Buzzwords hide the absence of thought; nothing is testable | Restate plainly; if it becomes obvious or empty, cut it | +| Refusing to choose | Pleasing every stakeholder concentrates nothing | Name what you will not do; accept that choice creates losers | +| Dog's-dinner objectives | Forty "priorities" means none; resources spread to uselessness | Pick one to three proximate objectives; park the rest | +| Blue-sky objectives | Restates the desired end state; the team cannot see how | Choose targets close enough to actually hit | +| Spreading resources evenly | Below-threshold effort everywhere produces results nowhere | Concentrate on the pivot point until wins are visible | +| Treating strategy as settled truth | Conditions change; a defended diagnosis goes stale | Review as a hypothesis; revise on evidence, on a cadence | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Does the document name the critical challenge? | Nothing can be evaluated or improved | Write the one-paragraph diagnosis before any goals | +| Is there a guiding policy that rules out whole classes of action? | It is a platitude, not a policy | Add "therefore we will not..." statements until it bites | +| Are actions coordinated and resource-backed? | It is a wish list | Give each action an owner, budget, date, and a reinforcing role | +| Would the strategy be wrong for your nearest competitor? | It is generic fluff | Anchor it in your specific asymmetries and obstacles | +| Is the first objective close enough to actually hit? | Blue-sky target; the team stalls | Set a proximate objective with an owner and a done-test | +| Does the plan exploit a wave, asymmetry, or rival's inertia? | Strength is matched against strength | Find leverage: anticipation, pivot point, concentration | +| Is there an explicit list of what you will not do? | Scope creeps back to everything | Write the no-list next to the action list | +| Has anyone tried to destroy this strategy before adopting it? | First conclusions ship untested | Run create-destroy with a virtual panel of experts | + +## Further Reading + +- [*"Good Strategy Bad Strategy: The Difference and Why It Matters"*](https://www.amazon.com/Good-Strategy-Bad-Strategy-Difference/dp/0307886239?tag=wondelai00-20) by Richard Rumelt +- [*"The Crux: How Leaders Become Strategists"*](https://www.amazon.com/Crux-How-Leaders-Become-Strategists/dp/1541701240?tag=wondelai00-20) by Richard Rumelt +- [*"Playing to Win: How Strategy Really Works"*](https://www.amazon.com/Playing-Win-Strategy-Really-Works/dp/142218739X?tag=wondelai00-20) by A.G. Lafley & Roger L. Martin +- [*"7 Powers: The Foundations of Business Strategy"*](https://www.amazon.com/7-Powers-Foundations-Business-Strategy/dp/0998116319?tag=wondelai00-20) by Hamilton Helmer + +## About the Author + +**Richard Rumelt** is professor emeritus at UCLA Anderson School of Management and one of the world's most influential thinkers on strategy — McKinsey Quarterly dubbed him "the strategist's strategist," and The Economist named him among the 25 most influential living management thinkers. He distilled four decades of research and consulting into *Good Strategy Bad Strategy* (2011) and *The Crux* (2022). diff --git a/.agents/skills/good-strategy-bad-strategy/references/bad-strategy.md b/.agents/skills/good-strategy-bad-strategy/references/bad-strategy.md new file mode 100644 index 00000000..4a07c88d --- /dev/null +++ b/.agents/skills/good-strategy-bad-strategy/references/bad-strategy.md @@ -0,0 +1,139 @@ +# Detecting Bad Strategy + +## Table of Contents + +- [Bad Strategy Is Its Own Species](#bad-strategy-is-its-own-species) +- [Hallmark 1: Fluff](#hallmark-1-fluff) +- [Hallmark 2: Failure to Face the Challenge](#hallmark-2-failure-to-face-the-challenge) +- [Hallmark 3: Mistaking Goals for Strategy](#hallmark-3-mistaking-goals-for-strategy) +- [Hallmark 4: Bad Strategic Objectives](#hallmark-4-bad-strategic-objectives) +- [Why Bad Strategy Proliferates](#why-bad-strategy-proliferates) +- [Auditing a Strategy Deck Section by Section](#auditing-a-strategy-deck-section-by-section) +- [The Audit Report Format](#the-audit-report-format) + +## Bad Strategy Is Its Own Species + +Bad strategy is not the absence of strategy, and it is not a good strategy that failed. It is a recognizable construction with its own logic: it skips the hard work of diagnosis and choice, and fills the space with substitutes — buzzwords, ambitions, templates, and positive thinking. Because it has structure, it can be detected systematically. Hunt for the four hallmarks below; finding any one is a finding, finding three is a verdict. + +## Hallmark 1: Fluff + +Fluff is gibberish masquerading as strategic concepts: inflated language, restated obviousness, and abstraction stacked on abstraction to create the illusion of high-level thinking. + +**Detection checklist:** + +- **Plain-language restatement.** Translate the sentence into ordinary words. If it collapses into the obvious ("our strategy is customer-centric intermediation" → "we are a bank"), it is fluff. +- **The negation test.** Negate the claim. If the negation is absurd — "we will *not* pursue excellence," "we will *not* put customers first" — the original carries zero information. +- **Buzzword density.** Count occurrences of *leverage, synergy, world-class, best-in-class, ecosystem, holistic, next-generation, win-win, empower* per page. More than two per page in load-bearing sentences is a red flag. +- **Abstraction stack.** If defining one term requires three more undefined terms ("a platform-led ecosystem strategy enabling scalable value creation"), the stack is hiding an empty center. +- **The Monday test.** Ask: what would someone do differently on Monday because of this sentence? No answer, no content. + +**Before:** "Our strategy is to leverage best-in-class AI capabilities and a customer-obsessed culture to deliver differentiated, scalable value across the full customer lifecycle." + +**After (plain restatement):** "We use AI and try to be good to customers" — which every competitor would also claim. A real replacement: "We will win mid-market support teams by being the only vendor whose agent resolves tickets end-to-end inside Zendesk — accepting that enterprises with custom stacks are not our market." + +## Hallmark 2: Failure to Face the Challenge + +If a strategy document does not name and analyze the obstacle, there is no way to evaluate the strategy or improve it. International Harvester's 1979 plan was full of projections and initiatives — and never mentioned its famously toxic labor relations, the actual problem that sank it. The omission is rarely accidental: naming the challenge embarrasses someone or implies a painful choice. + +**Detection checklist:** + +- Search the document for an obstacle. Is there a section that says what stands in the way? (Not "risks" boilerplate — the actual difficulty.) +- Does it explain *why* performance is what it is — why deals are lost, why churn rose, why the last plan missed? +- Would a smart new executive, reading only this document, learn what is hard about this business right now? +- Are competitors named, with the specific reason they win when they win? +- Is anything in the document unflattering to the team that wrote it? A document with no self-implicating facts has been sanitized. + +**Before:** "Building on our momentum, we will accelerate growth through product-led expansion, strategic partnerships, and operational excellence." + +**After:** "Inbound demand fell 40% in two quarters because AI answers absorbed the search traffic our content funnel depended on. Our growth model — SEO → trial → sales-assist — is structurally broken at the top. The challenge is rebuilding demand generation around channels we can defend." Now a strategy can exist, because there is something for it to overcome. + +## Hallmark 3: Mistaking Goals for Strategy + +Goals are ambitions: revenue targets, market-share numbers, "20% growth." Strategy is the lever — the diagnosis and approach that make the ambition achievable. A CEO whose plan is "20/20: twenty percent growth, twenty percent margin" plus exhortation to push harder has a desire and a pep talk, not a strategy. + +**Detection checklist:** + +- **Verb audit.** Circle the verbs in the "strategy" section. *Achieve, grow, increase, deliver, drive, accelerate, maximize* are ambition verbs. *Concentrate, exit, rebuild, target, replace, consolidate* are choice verbs. A section with only ambition verbs is a goals list. +- **Mechanism check.** For each number, is there an answer to "what changes in the world or in our conduct that produces this?" +- **Effort substitution.** Phrases like "relentless execution," "raising the bar," "one team, one dream" used as the *how* signal motivation standing in for method. +- **Source of the number.** Was the target derived from a diagnosis ("fixing activation should lift conversion from 9% to 15%") or from desire ("the board wants 2x")? + +**Before:** "Our strategy for FY26: grow ARR 25%, raise NRR to 115%, launch 12 features, expand to two new regions." + +**After:** "Diagnosis: expansion revenue stalled because our pricing caps usage growth. Guiding policy: re-price around the metric that scales with customer value (documents processed), concentrating sales on the 200 accounts hitting plan ceilings. Actions: usage-based tier (Q1), migration playbook for the 200 accounts (Q1-Q2), retire per-seat plans for new sales (Q2). The 25% ARR target is the *forecast* of this working — not the strategy." + +## Hallmark 4: Bad Strategic Objectives + +Even when leaders move past fluff and goals, they can produce objectives that no one can act on. Two failure shapes: + +**The dog's dinner** — a long list of "strategic priorities" that is really a union of every department's wish list. One city's strategic plan contained 47 "strategies" and 178 action items; item 122 was "create a strategic plan." Tests: + +- Count the "priorities." More than five means none are priorities. +- Check for resourcing. If the list exceeds what the org can staff, it is a wish list, not a plan. +- Check for conflict. Real choices conflict with something; a list where nothing conflicts with anything was assembled, not chosen. + +**The blue sky** — an objective that simply restates the desired end state, skipping over the gap between here and there: "become the #1 platform," "be the most trusted brand in the category." Tests: + +- Can the team see *how*? If the objective is as hard to act on as the original challenge, it has added nothing. +- Is it a re-description of winning? "Win the market" is not an objective; "win 10 of the 30 design-partner candidates in fintech by June" is. +- Does it resolve ambiguity, or just relocate it? + +**Before:** "Strategic priorities: 1) Delight customers 2) Win the enterprise 3) Build a world-class team 4) Operational excellence 5) Innovate boldly 6) Expand internationally 7) Strengthen the brand..." (and 16 more). + +**After:** "Objective for the next two quarters: make the EU instance fully self-serve — signup to production without a sales call — because the diagnosis shows sales-assisted onboarding caps us at 40 deals/quarter. Everything on the old list that does not serve this is parked." + +## Why Bad Strategy Proliferates + +Detection improves when you know why bad strategy gets written despite everyone preferring good strategy. + +**1. Choice is painful.** A real guiding policy rules things out, and every ruled-out option has a sponsor. Faced with that conflict, leaders produce "strategies" that fund everything a little — universal buy-in, zero concentration. Digital Equipment Corporation's leadership, unable to choose among three rival futures, blended them into "DEC is committed to providing high-quality products and services and being a leader in data processing" — mush that chose nothing while the company sank. When you see mush, look for the unresolved fight underneath it. + +**2. Template-style planning.** A whole industry sells the fill-in-the-blanks format: Vision → Mission → Values → Strategies. The template manufactures documents that look complete while containing no diagnosis and no choice — the "strategies" slot gets filled with goals because nothing upstream forced an analysis of the obstacle. The template is how organizations produce bad strategy *in good faith*. + +**3. New Thought culture.** A nineteenth-century idea — that visualizing success produces success — survives in business as the cult of vision: believe, project confidence, never entertain doubt. It makes diagnosis feel disloyal ("too negative") and substitutes shared belief for analysis. The tell: a document whose emotional register is inspiration throughout, with no section that could disappoint anyone. + +## Auditing a Strategy Deck Section by Section + +A practical procedure for auditing a strategy document, deck, or annual plan: + +1. **Inventory.** List every section/slide. Classify each as: *diagnosis, guiding policy, action, goal, evidence, fluff, other.* Most decks classify as 60% goals + fluff, 0% diagnosis. +2. **Hunt the diagnosis.** Is there one falsifiable paragraph naming the critical challenge? If absent, the audit's top finding is already written. +3. **Test the policy.** Apply the negation test and the competitor-paste test (would this read as false in the rival's deck?). List what the policy rules out; if nothing, flag it. +4. **Test the actions.** Coherence (do they reinforce each other?), resourcing (owners, budgets, dates?), and traceability (does each serve the policy?). Orphan actions reveal the real, unstated strategy: momentum. +5. **Apply the hallmark checklists** above to the remaining sections; log each hit with a quote. +6. **Score it** on the skill's 0-10 scale and write the rewrite path: which sections to delete, which single paragraph to write first (always the diagnosis), which list to cut to three. + +| Deck section | What to look for | Typical red flag | +|--------------|------------------|------------------| +| "Vision / Mission" | Anything load-bearing | Strategy expected to live here — it can't | +| "Market" | Facts that imply the obstacle | TAM slides with no implication for conduct | +| "Strategy" | A guiding policy | Goals with ambition verbs; platitudes | +| "Strategic priorities" | 1-3 choices that conflict with something | 10+ items; every department represented | +| "Roadmap / Initiatives" | Coherence and resourcing | Independent projects; nothing stopped | +| "Financials" | Forecast linked to mechanism | Hockey stick justified by "momentum" | + +## The Audit Report Format + +Deliver findings in this shape: + +``` +STRATEGY AUDIT: [document name] +Score: X/10 (skill scoring bands) + +THE CHALLENGE THE DOCUMENT FACES (or fails to): +[your one-paragraph statement of what the real challenge appears to be] + +HALLMARK FINDINGS: +- Fluff: [quote] → [plain restatement] → [verdict] +- Challenge: [named? where? what's missing] +- Goals-as-strategy: [quote] → [the missing mechanism] +- Bad objectives: [dog's dinner / blue sky, with counts] + +WHAT SURVIVES: [sections worth keeping, evidence worth reusing] + +REWRITE PATH: +1. Write the diagnosis paragraph (draft provided below) +2. [specific next steps — policy candidates, list cuts, no-list] +``` + +Lead with the diagnosis you believe the document avoided — an audit that only criticizes is itself a dog's dinner. The goal is not to shame the deck but to leave its owners one page away from a real kernel. diff --git a/.agents/skills/good-strategy-bad-strategy/references/case-studies.md b/.agents/skills/good-strategy-bad-strategy/references/case-studies.md new file mode 100644 index 00000000..e7d6a655 --- /dev/null +++ b/.agents/skills/good-strategy-bad-strategy/references/case-studies.md @@ -0,0 +1,133 @@ +# Case Studies: Good Strategy Bad Strategy in Practice + +## Table of Contents + +- [Case Study 1: Auditing a SaaS Annual Plan](#case-study-1-auditing-a-saas-annual-plan) +- [Case Study 2: A Startup Chooses Where to Concentrate](#case-study-2-a-startup-chooses-where-to-concentrate) +- [Case Study 3: Rewriting a Vision Deck into a Kernel](#case-study-3-rewriting-a-vision-deck-into-a-kernel) +- [Key Takeaways](#key-takeaways) + +## Case Study 1: Auditing a SaaS Annual Plan + +### Context + +A 60-person B2B SaaS company sells compliance-training software to mid-market HR teams. $9M ARR, growth slowing from 40% to 12% year over year. The leadership team produced a 34-slide annual plan titled "Strategy FY27" and asked for a review before presenting it to the board. + +### The Document + +The deck contained: a vision slide ("To be the most trusted partner in workforce compliance"), three values slides, a market-size slide ($4.2B TAM), targets (25% ARR growth, NRR from 103% to 112%, logo churn under 8%), and fourteen initiatives spanning every department — AI course generation, a manager dashboard, SOC 2 Type II, a partner program, two new verticals, a website refresh, and eight more. + +### Applying the Skill + +**Step 1 — Inventory and classification.** Every slide was classified as diagnosis, policy, action, goal, evidence, or fluff. Result: 0 diagnosis slides, 0 policy slides, 19 goal/initiative slides, 6 fluff slides, 9 evidence slides. The headline finding wrote itself: the plan contained targets and activities but no statement of what stands in the way. + +**Step 2 — Hallmark scan.** Fluff: "trusted partner in workforce compliance" failed the negation test (no rival aspires to be untrusted). Goals for strategy: the verb audit found *grow, increase, deliver, expand, accelerate* — not one choice verb. Bad objectives: fourteen initiatives for nine engineers was a dog's dinner; nothing conflicted with anything, the signature of an assembled rather than chosen list. + +**Step 3 — Hunting the missing diagnosis.** The audit reconstructed the challenge from evidence the deck itself contained but never confronted: 70% of historical leads came from SEO content; organic traffic was down 45% in three quarters as AI answers absorbed compliance questions; win rates were stable. The company did not have a growth problem — it had a demand-generation collapse the plan never mentioned, plus a quieter fact buried in the churn appendix: accounts using the audit-trail feature churned at one-third the rate of the rest. + +**Step 4 — Kernel rewrite.** Working session with the exec team produced one page: + +- **Diagnosis:** Our acquisition engine (SEO → trial) is structurally broken by AI search, and we are funding fourteen initiatives as if it still worked. Meanwhile our stickiest value — audit-proof training records — is treated as a feature, not the product. +- **Guiding policy:** Reposition from "training content" to "audit protection" — the system of record HR shows the regulator — and rebuild demand on channels AI answers cannot absorb: compliance-auditor partnerships and integration marketplaces. Therefore we will not: chase the two new verticals, build AI course generation this year, or bid on broken SEO terms. +- **Coherent actions:** (1) Audit-trail becomes the lead product and demo (product, Q1); (2) partner program rebuilt exclusively for compliance auditors and HRIS marketplaces (one senior hire, Q1-Q2); (3) pricing anchored to audit risk, not seat count (Q2); (4) kill eight initiatives, redeploying six engineers (immediately). + +### Outcome + +| Aspect | Before | After | +|--------|--------|-------| +| Plan length | 34 slides | 1 kernel page + 6 evidence slides | +| Initiatives | 14 | 4 coordinated actions + kill list | +| Challenge named | Nowhere | First paragraph | +| Board reaction | (prior year) "ambitious" | "First time we understood the business" | +| Two quarters later | — | Partner-sourced pipeline 0% → 31%; NRR 103 → 109 | + +### Lessons + +1. The decisive audit move was classification — counting zero diagnosis slides ended the debate about whether the plan was a strategy. +2. The diagnosis was already in the appendix data; bad strategy is usually evidence avoidance, not evidence absence. +3. The kill list freed more capacity than any hiring plan could have. + +## Case Study 2: A Startup Chooses Where to Concentrate + +### Context + +A seed-stage startup (9 people, $1.8M raised, 13 months of runway) sells an AI agent that turns sales calls into CRM updates. $21K MRR spread across three customer types: SMB sales teams, recruiting agencies, and management consultants. Each segment uses the product differently; the roadmap is a queue of per-segment requests. Growth is 4% a month and the founders disagree about where to push. + +### Applying the Skill + +**Step 1 — Name the pattern.** The diagnosis workshop recognized a threshold shortfall: three motions, none past the visibility threshold. Nine people cannot hold three ICPs above threshold; the strategy question was not "how do we grow" but "where do we concentrate." + +**Step 2 — Anticipation scan.** The team wrote the "announced futures" register. Decisive entry: the two dominant CRMs had both announced native call-summary features shipping within a year. Generic "calls → CRM notes" was a dying wedge — whatever segment they chose had to be one where native features would still lose. + +**Step 3 — Score the segments against sources of power.** Each segment was scored 1-5 on: pull (inbound, usage depth), asymmetry (why incumbents/native features can't serve it), isolating-mechanism potential (what compounds), and threshold reachability within runway. + +| Criterion | SMB sales | Recruiting agencies | Consultants | +|-----------|-----------|--------------------:|-------------| +| Pull today | 3 | 4 | 2 | +| Asymmetry vs. native CRM features | 1 — head-on | 4 — ATS fragmentation, candidate + client double-entry | 3 — but bespoke workflows | +| Isolating-mechanism potential | 1 | 4 — placement-outcome data network | 2 | +| Threshold within 13 months | 2 — broad market | 4 — dense niche, 3 conferences, 2 communities | 2 | +| **Total** | **7** | **16** | **9** | + +Recruiting agencies won on the only criterion that mattered most: the CRM vendors' announced features (anticipation) would commoditize the sales use case first, while recruiting ran on fragmented ATSes the natives would not prioritize — a rival's-roadmap asymmetry plus a reachable, dense niche. + +**Step 4 — Set the proximate objective and the no-list.** High ambiguity ruled out a revenue target. The proximate objective: *in 8 weeks, 20 recruiting agencies live, with intake-call → ATS + client-update workflow complete end-to-end, and weekly usage retention above 60%.* The no-list: no new SMB sales features, no consultant customizations, sunset both with 90-day migration help, decline non-recruiting inbound. + +**Step 5 — Create-destroy before commit.** One founder spent two days building the case *against* recruiting (small TAM, ATS API risk, agency churn). The attack surfaced a real rabbit hole — two ATS APIs covered only 60% of target agencies — which became action item one (integration coverage) instead of a Q3 surprise. The bet survived its own destruction and shipped. + +### Outcome + +Six months later: $58K MRR, 96% from recruiting; growth 11% monthly; the placement-outcome dataset (which intake answers predict successful placements) became the demo's closing slide — an isolating mechanism no horizontal note-taker had. The CRM-native features shipped as predicted and erased three of the startup's former competitors. One founder's note: "Choosing felt like killing two-thirds of the company. It was the first day the company existed." + +### Lessons + +1. Anticipation — reading rivals' announced roadmaps — eliminated an option that pull alone would have kept alive. +2. The scoring table did not make the choice; it forced the disagreement into criteria, where it could be resolved. +3. Create-destroy converted the riskiest unknown into the first action item. + +## Case Study 3: Rewriting a Vision Deck into a Kernel + +### Context + +A 200-person payments scale-up prepared for its Series C with an offsite that produced a 30-slide "Vision 2030" deck: mission, five values, five strategic pillars (Growth, Innovation, Customers, People, Excellence), and 23 initiatives distributed under the pillars. A board member's only comment: "This is lovely. What's the strategy?" The CEO brought the deck to a working group with this skill. + +### Applying the Skill + +**Step 1 — Honest classification.** The group labeled every slide. Pillars were categories, not choices — each one passed the negation test into absurdity ("we will not pursue Excellence"). The 23 initiatives mapped 1:1 to org-chart departments: the deck was the org chart wearing a costume, the signature of unwillingness to choose. + +**Step 2 — Force candidate diagnoses.** Instead of debating pillars, each of five leaders wrote a one-paragraph diagnosis of the single critical challenge. Three candidates emerged: (a) enterprise deals stall in security review; (b) unit economics depend on interchange fees that regulators in two core markets have signaled they will cap; (c) product breadth has outrun reliability. + +**Step 3 — Create-destroy with a virtual panel.** Each candidate was attacked through three personas: a skeptical CFO ("show me the number"), a churned customer, and the rival's head of product ("which diagnosis would I *hope* they pick?"). The interchange-cap diagnosis (b) survived strongest: the CFO persona found 61% of gross margin exposed to announced regulatory intent — a wave, with a date range. Candidates (a) and (c) were real but downstream: both became easier with the margin problem named, failing the unlock test in reverse. + +**Step 4 — Write the kernel.** + +- **Diagnosis:** 61% of gross margin rides on interchange fees that two regulators have signaled they will cap within ~three years. Our "vision" assumes an economic engine that is scheduled to shrink; every initiative priced against it is built on sand. +- **Guiding policy:** Shift the revenue base from payment rails to the software workflow around money movement — reconciliation, spend controls, forecasting — where willingness-to-pay survives fee caps, concentrating on the 400 mid-market customers who already use two or more workflow features. Therefore we will not: expand to new payment geographies this cycle, compete on rail pricing, or fund initiatives that scale fee-dependent volume. +- **Coherent actions:** (1) Software-revenue line target with its own owner (CRO, immediate); (2) workflow suite packaged and priced standalone (product, two quarters); (3) the 400-account expansion motion staffed by reassigning the geo-expansion team (Q1); (4) initiative review: each of the 23 initiatives re-justified against the policy. +- **Review trigger:** any regulatory ruling, or software revenue share below 25% by year-end. + +**Step 5 — The cull.** Against the policy, 14 of 23 initiatives were killed or parked, including two sacred ones (a consumer app pilot and a sponsorship). The remaining nine were re-sequenced so each fed the software-revenue shift. The five pillars were retired; the values slides moved to the employee handbook, where they belonged. + +### Outcome + +| Aspect | Vision deck | Kernel | +|--------|------------|--------| +| Length | 30 slides | 1 page + appendix | +| Initiatives | 23 unranked | 9, sequenced, each policy-traced | +| Margin exposure named | No | First paragraph, quantified | +| Series C diligence | — | Kernel reused verbatim in the data room | +| One year later | — | Software revenue 14% → 33% of gross margin | + +### Lessons + +1. "What's the strategy?" is answered by a diagnosis, never by pillars — categories are where choices go to hide. +2. The virtual panel converted a political fight (whose diagnosis wins) into an analytical one (which diagnosis survives attack). +3. Retiring the vision deck cost nothing: mission and values survived intact in their proper home, and the strategy finally existed. + +## Key Takeaways + +1. **Classification beats argument.** Counting diagnosis slides (usually zero) settles "is this a strategy?" faster than any debate. +2. **The diagnosis is usually avoidable evidence, already in hand.** Appendix churn tables, announced regulations, rivals' public roadmaps — bad strategy is the art of not looking. +3. **Choice creates losers, and that is the point.** Every case required killing real work with real sponsors; the relief came after, never before. +4. **Proximate objectives make strategy executable under ambiguity.** Eight-week, owner-named, done-testable targets moved teams that grand targets had stalled. +5. **Destroy your strategy before the market does.** Create-destroy and the virtual panel found the rabbit holes and weak diagnoses while they were still cheap. diff --git a/.agents/skills/good-strategy-bad-strategy/references/dynamics-inertia.md b/.agents/skills/good-strategy-bad-strategy/references/dynamics-inertia.md new file mode 100644 index 00000000..4eaebc30 --- /dev/null +++ b/.agents/skills/good-strategy-bad-strategy/references/dynamics-inertia.md @@ -0,0 +1,90 @@ +# Riding Dynamics, Fighting Inertia + +## Table of Contents + +- [Why Waves of Change Favor Attackers](#why-waves-of-change-favor-attackers) +- [Five Guideposts for Sensing Waves](#five-guideposts-for-sensing-waves) +- [Writing a Wave Brief](#writing-a-wave-brief) +- [The Three Inertias](#the-three-inertias) +- [Entropy](#entropy) +- [Attacker Playbooks](#attacker-playbooks) +- [Notes for Defenders](#notes-for-defenders) + +## Why Waves of Change Favor Attackers + +In stable periods, incumbents win: scale, brand, distribution, and accumulated learning compound in their favor, and a second-rate strategy is enough. Waves of change — technology shifts, deregulation, demographic and cost-structure changes — reset the contest. The incumbent's optimized machine is optimized for the old world; its margins are hostage to the old model; its people were promoted for mastering rules that no longer apply. For an attacker, a wave is exogenous leverage: you do not have to create the shift, only to see its implications earlier and commit to them more coherently than those who cannot. + +The discipline is seeing the wave *as it is breaking* — not predicting the far future. Most of what matters has already happened: the cost curve has already bent, the rule has already been announced, the behavior has already shifted in the youngest cohort. Strategy reads the present closely rather than the future speculatively. + +## Five Guideposts for Sensing Waves + +Use these as a standing checklist whenever an industry feels like it is moving. + +**1. Rising fixed costs.** When the cost of staying at the technical frontier rises sharply (R&D, content, capital equipment), the industry consolidates around the few who can pay, and everyone else must reposition. Detection questions: What does it cost to field a competitive offering today vs. five years ago? Who can no longer afford the table stakes? Product read: frontier-model training costs consolidate AI infrastructure into a handful of labs — so most companies' strategies should assume models are rented, not owned, and differentiation must live in data, workflow, and distribution built *on top* of the consolidating layer. + +**2. Deregulation — and rule changes generally.** When governments or platform owners change the rules (deregulation, new compliance regimes, app-store policy, privacy frameworks), the value pool is re-divided. Incumbents systematically misjudge the new world: they keep prices and cross-subsidies anchored to the old regime, overpay to defend formerly protected businesses, and underinvest where the new rules open ground. Detection questions: Which prices in this industry exist only because a rule made them possible? Whose cross-subsidy becomes untenable? Product read: a platform's API pricing change or a new AI act is a re-division of the pool — map who was subsidized by the old rules and serve the newly orphaned. + +**3. Predictable biases.** In transitions, people forecast badly in patterned ways: they extrapolate the present (assuming growth continues because it has), assume the old normal will return, imitate the most visible player, and pile into whatever the herd funds. Each bias is exploitable by whoever bets on the underlying mechanics instead. Detection questions: What does everyone currently assume continues forever? Where is capital crowding on momentum rather than mechanism? The contrarian opportunity is rarely "the opposite" — it is the specific spot the herd's simplification ignores. + +**4. Incumbent response.** Incumbents respond to waves in predictable defensive shapes: protect the legacy margin (milk the old business rather than cannibalize it), retreat upmarket toward their best customers, bundle the threatened product into suites, and announce hybrid offerings that preserve the old economics. Each defensive move tells you where the door is open. Detection questions: Read the incumbent's earnings calls — what number are they defending? What would they have to destroy internally to follow you? Product read: when the suite vendor responds to your point product by bundling harder, they are conceding the standalone market's users while defending the CFO relationship — choose which contest you want. + +**5. Attractor states.** An attractor state is where the industry "should" end up given technology and cost fundamentals — the configuration that would emerge if efficiency alone decided. "All data transport becomes IP" was telecom's attractor state; Cisco rode it for a decade while incumbents protected circuit-switched margins. Attractor states discipline wishful thinking because they are grounded in demand and cost logic, not in your hopes. Detection questions: In the efficient end state, who does the work, who gets paid, and which of today's toll booths still exist? What accelerants (cost curves, standards) and impediments (regulation, switching costs, installed bases) set the pace? Product read: "routine support tickets get resolved by software" is an attractor state; the strategic questions are pace and who owns the workflow when it arrives. + +## Writing a Wave Brief + +Condense the guideposts into a one-page brief before betting a roadmap on a wave: + +``` +WAVE BRIEF: [shift name, date] +What already changed: [cost curves, rules, behaviors — facts, not forecasts] +Guidepost readings: [fixed costs / rules / biases / incumbent response / attractor state] +Who is mispositioned: [incumbents and why their economics block response] +The attractor state: [who does the work, who gets paid, when] +Timing risk: [what makes this slower than it looks; can we survive being early?] +Our asymmetry on this wave: [why us] +``` + +The timing line is mandatory. Waves reliably take longer than enthusiasts expect — being early without the runway to wait is indistinguishable from being wrong. + +## The Three Inertias + +Inertia is an organization's inability or unwillingness to adapt. Diagnose the type before prescribing — or before attacking — because each has a different mechanism. + +| Type | Mechanism | Signs | Fix (incumbent) | Attack (challenger) | +|------|-----------|-------|-----------------|---------------------| +| Routine | Old playbooks keep executing | Metrics, pricing, and processes from the previous era | New metrics, outside hires, forced exposure to lost deals | Compete where the playbook misfires | +| Culture | Identity blocks adaptation | "We are an X company"; sacred projects; new ventures starved | Simplify, break insulated units, change leaders; takes years | Announce the future loudly — their culture will deny it | +| Proxy | Customers' inertia shields the incumbent | Incumbent profits from customers not switching | Painful: moving first cannibalizes today's profit | Collapse the customers' switching cost directly | + +**Inertia by routine** is the mildest: the organization *could* adapt but its standard procedures keep reproducing yesterday's answers — airlines after deregulation kept the route, pricing, and staffing formulas of the regulated era for years. The cure is changing what gets measured and who is hired; the attack is simply moving where the routine gives wrong answers. + +**Inertia by culture** is deeper: adaptation threatens identity, status hierarchies, and internal coalitions. Engineering-led cultures dismiss design threats; sales-led cultures dismiss self-serve. Renewal requires simplification first — killing the overgrowth of units, initiatives, and committees in which the old culture lives — then breaking the political structure, then rebuilding. Leaders who skip to "rebuilding" with a new slogan change nothing. + +**Inertia by proxy** is the subtle one: the incumbent is not asleep — it is *rationally* unresponsive because its profits ride on its customers' inertia. Banks paid low deposit rates while money-market funds grew because most depositors didn't move, and repricing for everyone to retain the few who did would have destroyed margin. The attack: make switching trivial and visible — one-click data migration, automatic import, side-by-side statements. When the customers' inertia breaks, the incumbent's position collapses quickly and it has no practiced response, because its "strategy" was the inertia itself. + +## Entropy + +Entropy is drift, not resistance: absent active management, organizations blur. Product lines proliferate and overlap; prices drift toward undisciplined discounts; cross-subsidies appear that nobody chose; ownership fuzzes. GM's brands — once a clean price-quality ladder from Chevrolet to Cadillac — drifted over decades into overlapping offerings that competed with each other and stood for nothing. + +Entropy matters to strategists for two reasons: weeding it from your own garden is valuable work even with no competitor in sight, and a rival's entropy is a map of your opportunity. + +**Entropy audit (quarterly or annual):** + +1. Plot every product/plan/SKU by price against the customer need it serves. Overlaps are entropy; so are gaps everyone assumed someone owned. +2. Trace margin by offering. Unchosen cross-subsidies — profitable line A quietly funding zombie line B — get a decision: re-price, kill, or *choose* the subsidy explicitly. +3. List the discounts, exceptions, and custom deals added in the last two years. Each was locally rational; ask what the set does to the price ladder. +4. Re-draw the intended structure (clean ladder, named segments, one owner per line) and schedule the cuts. + +The test for entropy is the *no-competition test*: if these blurred lines and leaky prices would still be wrong with zero competitors, the problem is entropy, and the fix is housekeeping, not repositioning. + +## Attacker Playbooks + +**Playbook A — Margin shadow.** Exploit an incumbent defending legacy margins. (1) Identify the revenue line they cannot cannibalize — seat licenses, services attach, transaction fees. (2) Configure your economics so following you destroys that line: usage-based pricing against per-seat, software against their services revenue. (3) Take the customers they rationally sacrifice first (small, price-sensitive, modern-stack), then move up. Requirement: your cost structure must be *structurally* lower, not VC-subsidized — a subsidy shadow evaporates. Risk: an incumbent with a board-level crisis may burn the boats and follow anyway; watch for leadership change as the signal. + +**Playbook B — Wave rider.** Pick the wave with the guideposts, then commit with a design-type strategy configured for the attractor state: every piece — pricing, architecture, hiring, channel — presupposing the new world, with no hedge dragging the old one along. Set a proximate-objective ladder (resolve ambiguity in weeks, capability in quarters) rather than a five-year vision. Risk is timing: size the bet to survive the wave arriving two years late. + +**Playbook C — Proxy breaker.** Attack the customer inertia that shields the incumbent. Make migration the product: importers, parallel-run modes, switching concierges, contract buyouts. Aim at moments when inertia naturally breaks — renewals, audits, platform deprecations, a champion changing jobs — and instrument them. Risk: switching subsidies attract deal-shoppers; qualify for fit, not just willingness to leave. + +## Notes for Defenders + +If you are the incumbent: run the guideposts against yourself annually; diagnose which inertia you have before launching a "transformation" (the fixes are different and culture-stage fixes take years you must start now); weed entropy on a calendar, not when crisis forces it; and when a wave is real, judge your response by what it does to the attacker's economics, not by how well it protects this year's margin — the margin you are defending is often the door you are holding open. diff --git a/.agents/skills/good-strategy-bad-strategy/references/kernel.md b/.agents/skills/good-strategy-bad-strategy/references/kernel.md new file mode 100644 index 00000000..351c6a19 --- /dev/null +++ b/.agents/skills/good-strategy-bad-strategy/references/kernel.md @@ -0,0 +1,162 @@ +# Writing the Kernel + +## Table of Contents + +- [What the Kernel Is](#what-the-kernel-is) +- [Diagnosis Craft](#diagnosis-craft) +- [Formulating the Guiding Policy](#formulating-the-guiding-policy) +- [Designing Coherent Actions](#designing-coherent-actions) +- [The Kernel Template](#the-kernel-template) +- [Worked Example 1: Seed-Stage Startup](#worked-example-1-seed-stage-startup) +- [Worked Example 2: Established Product](#worked-example-2-established-product) +- [When Is a Kernel Done](#when-is-a-kernel-done) + +## What the Kernel Is + +The kernel is the minimum viable structure of a strategy: a **diagnosis** that defines the nature of the challenge, a **guiding policy** that commits to an overall approach for dealing with it, and a set of **coherent actions** that carry the policy out. Everything else in a strategy document — market sizing, vision statements, financial projections — is either input to the kernel or decoration around it. + +The kernel deliberately excludes things most strategy documents lead with: + +| Common plan artifact | What it actually is | Kernel replacement | +|---------------------|--------------------|--------------------| +| Vision statement | A description of a desired future | Diagnosis of what stands between you and any future | +| Mission and values | Identity and conduct norms | Nothing — they are fine, but they are not strategy | +| Goals and targets ("$10M ARR") | Ambitions; outputs of strategy | Guiding policy: the approach that could produce them | +| List of initiatives | Department wish lists | Coherent actions that reinforce one another | +| SWOT grid | Raw material | A judgment about which item on the grid is *the* challenge | + +A kernel fits on one page. If it does not, you have not finished choosing. + +## Diagnosis Craft + +The diagnosis is the most skipped and most valuable element. It is a judgment — a simplification of messy reality that names the critical challenge and, implicitly, what kind of situation you are in. Get it wrong and everything downstream is coordinated effort aimed at the wrong target. + +### Finding the critical challenge + +1. **Collect the raw mess.** List every problem, threat, complaint, and stalled ambition: churn numbers, lost-deal notes, competitor moves, team frustrations. Do not filter yet. Aim for 15-30 items. +2. **Cluster into candidate challenges.** Group items that share a cause. "Sales cycle lengthening," "champions ghosting," and "more stakeholders per deal" might all cluster into "our buyer changed." +3. **Apply the unlock test.** For each candidate ask: *if this were solved, how much of the rest of the list gets easier?* The critical challenge is upstream of many symptoms. +4. **Apply the addressability test.** Ask: *can we act on this with resources we have or can realistically get?* "The macro economy" fails; "our onboarding loses technical buyers" passes. +5. **Choose one.** The candidate scoring highest on unlock × addressability is your critical challenge — the crux. Naming two is allowed only if one is clearly sequenced behind the other. + +### Simplification and the courage to judge + +A diagnosis is not a list of facts; it is a claim about which facts matter. "We have 14 problems" is an inventory. "We are a chain-link system stuck at the activation link" is a diagnosis. The simplification feels risky — you are discarding real complexity — but an un-simplified situation cannot be acted on. Write the diagnosis as one falsifiable paragraph, not a slide of bullets. + +### Diagnosis by analogy + +Experienced strategists diagnose by pattern-matching the situation to known structures. Useful patterns: + +| Pattern | Signature | What it implies | +|---------|-----------|----------------| +| Chain-link stuck | Several functions adequate, one weak; global metrics frozen | Fix the weakest link first; ignore global metrics meanwhile | +| Wave of change | Cost structures or rules shifting industry-wide | Position for the attractor state; exploit incumbent inertia | +| Entropy / blur | Overlapping products, drifting prices, fuzzy ownership | Clean house before seeking new advantage | +| Strength-on-strength | You compete head-on where the rival is strongest | Re-segment; find ground where their strength is irrelevant | +| Threshold shortfall | Effort spread thin; nothing reaches visible results | Concentrate; accept being absent elsewhere | + +### Tests of a good diagnosis + +- Names a cause or structure, not a symptom ("activation is broken," not "growth is slow") +- Falsifiable — specific enough that evidence could prove it wrong +- An informed skeptic would accept that the facts support it +- Points toward action without dictating it +- One paragraph, plain language, no fluff + +## Formulating the Guiding Policy + +The guiding policy is the overall approach for overcoming the diagnosed obstacles. It is not a goal (an outcome you want) and not an action (a step you will take). It is a method — guardrails that rule out vast realms of possible action and channel effort toward your sources of power: leverage, asymmetric advantage, a wave you can ride, a rival's inertia. + +**Drafting procedure:** + +1. Write three to five candidate policies in this form: *"We will [approach] by [where/how we concentrate], because [the asymmetry or leverage that makes it work for us specifically]."* +2. For each candidate, list at least three significant things it **rules out**. If you cannot, the candidate is a platitude — discard it. +3. Check each against the diagnosis: does it actually address the named obstacle, or just sound strategic near it? +4. Pick one. Two guiding policies means you have not chosen. + +**Tests of a good guiding policy:** + +- Rules out real options people currently want to pursue +- Exploits a named asymmetry — it would be a *bad* policy for your nearest competitor +- Short enough to repeat in meetings from memory +- Stable for quarters, not days — actions change faster than policy + +## Designing Coherent Actions + +Actions are where strategy becomes visible — and where most documents collapse into a list of independent department initiatives. Coherence means the actions are coordinated: each one makes the others more effective, and none works against another. + +**Design steps:** + +1. **Derive, don't collect.** Generate actions only from the guiding policy. Do not import the existing roadmap and relabel it. +2. **Run the coherence check.** For each pair of actions ask: does A make B easier, harder, or neither? A strategy whose actions are all "neither" is a list; any "harder" pair must be resolved now, not discovered in Q3. +3. **Back each action with resources.** Owner, people, budget, start date, done-test. An action nobody is staffed for is a hope. +4. **Write the stop-doing list.** Coherent action includes withdrawal: name the projects, segments, or features being stopped to fund the strategy. If nothing stops, nothing was chosen. +5. **Make the first step proximate.** Something concrete starts within two weeks. Distant-future actions are goals wearing costumes. + +## The Kernel Template + +``` +KERNEL: [name / date / author] + +DIAGNOSIS (one paragraph) +The critical challenge is [cause/structure, not symptom]. +Evidence: [2-4 facts that support it]. +This is a [pattern/analogy] situation. +What would prove this wrong: [signal]. + +GUIDING POLICY (one or two sentences) +We will [approach] by [concentration], because [our asymmetry]. +Therefore we will NOT: [3+ ruled-out options]. + +COHERENT ACTIONS (3-5, each resourced) +1. [Action] — owner, resources, start, done-test, reinforces #__ +2. ... +STOP DOING: [projects/segments/features being withdrawn] + +REVIEW: re-test diagnosis on [date / metric trigger]. +``` + +## Worked Example 1: Seed-Stage Startup + +**Situation:** Eight-person startup selling an AI code-review tool. $35K MRR, flat for five months. Self-serve signups convert at 9%; the team is split across building IDE plugins, a GitHub app, and an enterprise pilot. Two competitors are better funded. + +**Diagnosis:** "Growth is flat" is the symptom. The cluster analysis shows: trials stall before the tool sees a real pull request; setup requires CI changes most users abandon; the enterprise pilot consumes 40% of engineering for one logo. The critical challenge: **time-to-first-value is ~2 days in a market where rivals demo value in minutes — and our effort is spread across three motions, none past the visibility threshold.** Pattern: threshold shortfall plus a weak activation link. + +**Guiding policy:** *Win the GitHub-native mid-size team by being the only reviewer that shows a high-quality review on the customer's own code within 10 minutes of install, concentrating everything on that single motion.* Therefore we will NOT: pursue enterprise pilots this year, build IDE plugins, or support GitLab/Bitbucket. + +**Coherent actions:** + +1. Rebuild onboarding to run on a repo's last 20 merged PRs at install — no CI changes (2 engineers, starts Monday; done when median time-to-first-review < 10 min) +2. End the enterprise pilot; refund and refer (founder, this week) — frees the 40% that funds action 1 +3. Retarget all marketing to "first review in 10 minutes," with live public benchmark repos (1 marketer, 2 weeks) +4. Instrument the activation funnel install → first review → first comment accepted (1 engineer, 1 week) — the lab for testing the diagnosis + +Each action reinforces the others: the pilot's end staffs the rebuild; instrumentation proves or kills the diagnosis; marketing's promise is the product's new behavior. + +## Worked Example 2: Established Product + +**Situation:** Twelve-year-old field-service management platform, $28M ARR, serving HVAC, plumbing, landscaping, and cleaning companies. Renewals slipping (NRR 96%); a vertical-only HVAC rival wins on "built for HVAC" despite fewer features. Three pricing plans overlap; the roadmap is a union of the four industries' requests. + +**Diagnosis:** Not "the rival is cheaper" — win/loss notes show price is rarely decisive. Twelve years of serving four verticals created **entropy and below-threshold quality everywhere**: the product is 70% right for each industry while the rival is 95% right for one. Each vertical's requests dilute the others. Pattern: entropy plus strength-on-strength against a focused attacker. + +**Guiding policy:** *Re-concentrate as the system of record for mechanical trades (HVAC + plumbing), matching the vertical rival's fit while exploiting our one real asymmetry — ten years of job-cost data — to ship benchmarking no startup can copy.* Therefore we will NOT: build for landscaping/cleaning beyond maintenance mode, chase feature parity horizontally, or discount to save renewals. + +**Coherent actions:** + +1. Split the roadmap: 80% of engineering to mechanical-trades workflows; landscaping/cleaning enter maintenance mode with a 12-month support promise (VP Product, this quarter) +2. Ship job-cost benchmarking ("your margin vs. 4,000 mechanical contractors") as the renewal anchor (data team, 2 quarters; done at 30% renewal-conversation usage) +3. Collapse three overlapping plans into one mechanical-trades ladder; grandfather others (pricing lead, 6 weeks) +4. Retrain sales on a "built for mechanical trades" narrative with benchmark proof (sales enablement, parallel with 2) + +The stop-doing list is the strategy: maintenance mode funds the concentration, and the data asymmetry — not nostalgia for breadth — is what the rival cannot follow. + +## When Is a Kernel Done + +- Diagnosis: one falsifiable paragraph a skeptic would sign +- Guiding policy: one approach, three-plus ruled-out options, anchored in a named asymmetry +- Actions: 3-5, mutually reinforcing, each with owner/resources/date/done-test +- Stop-doing list exists and actually frees the resources the actions need +- The whole kernel fits on one page and can be explained aloud in five minutes +- A review trigger is set — date or metric — at which the diagnosis gets re-tested + +If the kernel passes all six, you have a strategy. If it fails any one, you have a draft — keep choosing. diff --git a/.agents/skills/good-strategy-bad-strategy/references/sources-of-power.md b/.agents/skills/good-strategy-bad-strategy/references/sources-of-power.md new file mode 100644 index 00000000..67b2ab29 --- /dev/null +++ b/.agents/skills/good-strategy-bad-strategy/references/sources-of-power.md @@ -0,0 +1,107 @@ +# Sources of Power + +## Table of Contents + +- [Choosing a Source of Power](#choosing-a-source-of-power) +- [Leverage](#leverage) +- [Proximate Objectives](#proximate-objectives) +- [Chain-Link Systems](#chain-link-systems) +- [Design-Type Strategy](#design-type-strategy) +- [Focus](#focus) +- [Using Advantage](#using-advantage) +- [Stacking Sources](#stacking-sources) + +## Choosing a Source of Power + +A guiding policy without a source of power is a wish. Before formulating policy, identify which asymmetry the strategy will run on: + +| Source | Core question | Reach for it when | +|--------|--------------|-------------------| +| Leverage | Where does a unit of effort buy the most result? | You can anticipate others' behavior or see a pivot point | +| Proximate objectives | What can we actually hit from here? | Ambiguity is high; teams stall on grand targets | +| Chain-link | Which link caps the whole system? | Effort everywhere, results nowhere | +| Design | What configuration of pieces wins? | Stakes are high and resources scarce | +| Focus | Which narrow target can we dominate? | Rivals serve everyone adequately, no one well | +| Advantage | What asymmetry do we already hold? | You have something rivals structurally cannot copy | + +## Leverage + +Strategic leverage comes from three multiplied ingredients: **anticipation**, a **pivot point**, and **concentration**. Each alone helps; together they let a small force move a large outcome. + +**Anticipation.** Most behavior is predictable: customers keep their habits, incumbents defend their margins, platforms follow announced roadmaps, regulators follow published calendars. You do not need to forecast the future — you need to notice commitments already made. When a major OS vendor announces privacy changes 18 months out, every business built on third-party tracking will predictably scramble; a startup that builds the first-party-data alternative *before* the deadline harvests the scramble. Practice: keep a one-page register of "announced futures" — platform deprecations, regulation effective dates, rivals' public commitments — and ask which one your roadmap exploits. + +**Pivot points.** A pivot point is a place where effort is amplified — where a small, feasible change releases a disproportionate result. Signatures of a pivot point: a constraint shared by all rivals that you alone can relax; a moment of peak user emotion (first run, failure, renewal) that nobody has designed; an imbalance between how much something matters to customers and how little attention it gets. Finding them is empirical: walk the customer journey and rank each step by (impact if 10x better) ÷ (cost to make it 10x better). + +**Concentration.** Effects become visible only past a threshold. Marketing in five channels at 20% intensity each typically produces nothing measurable in any of them; one channel at 100% breaks through, and the visible win compounds — it attracts talent, references, and belief. Concentration is painful precisely because it makes you absent elsewhere; that pain is the cost of crossing the threshold. Rule of thumb for early-stage products: if you cannot name the segment where you are *over*-investing relative to its current size, you are spread below threshold everywhere. + +**When to use:** whenever you can know or decide something rivals haven't — leverage is the default source of power for resource-poor attackers. + +## Proximate Objectives + +A proximate objective is a target close enough that the team can see how to hit it. Leaders who hand down objectives as hard to reach as the original challenge ("become the category leader") have not done their job; resolving ambiguity into feasible targets *is* the job. + +**Calibrate distance to ambiguity:** + +| Ambiguity level | Situation | Right objective distance | Example | +|-----------------|-----------|--------------------------|---------| +| Low | Stable market, known playbook | 12-month outcome targets | "Grow EU self-serve revenue 40%" | +| Medium | Known direction, unknown mechanics | One-quarter capability targets | "Stand up a working PLG funnel with 3 instrumented cohorts" | +| High | New market, new tech, shifting rules | 2-6 week ambiguity-resolving targets | "Run 15 problem interviews; decide wedge by March 15" | + +**Deciding the ambiguity away.** When the Surveyor program could not design a Moon lander because no one knew the lunar surface, a JPL engineer wrote a specification — firm enough to land on, specific slopes and granularity — and the program designed against it. The spec was a judgment, not a fact, but it converted an undesignable problem into an engineering problem. Product equivalent: when the team stalls on unknowables ("what will enterprise buyers require?"), *write the assumption down as a design spec*, date it, and build against it. Revise the spec when evidence arrives; never stall waiting for certainty. + +**Writing a proximate objective:** one owner; a done-test a outsider could verify; a deadline inside one planning horizon; and the team's honest answer to "can you see how?" is yes. Cascade them: each accomplished proximate objective creates new capabilities, which bring previously blue-sky targets into proximate range — strategy as a ladder, not a leap. + +**When to use:** always, as the bridge from policy to action — and especially when smart teams are stalled, because stalling usually means the objective is too far away, not the team too weak. + +## Chain-Link Systems + +A system is chain-linked when overall performance is capped by its weakest link — excellence in one stage adds nothing until the others match. The Challenger was lost to one O-ring. A product funnel is a chain: acquisition → activation → retention → expansion; a 10x improvement in acquisition poured into 15% activation is mostly waste. + +**Diagnosing a chain-link situation:** + +1. Map the links — the stages where value is created or lost (funnel stages, or the quality chain: data → model → UX → trust). +2. Set a "good enough" threshold per link, benchmarked against the best rival or user expectation. +3. Measure each link against its threshold. A chain-link diagnosis holds when one or two links sit far below threshold while others are at or above it. +4. Confirm the cap: improvements in strong links haven't moved the global metric. That is the signature. + +**Why chain-link systems get stuck:** fixing one link shows no system-level result (the next weak link now caps it), so the effort looks wasted and gets abandoned. Escaping requires a leader who takes responsibility for the *whole* chain, fixes links one at a time with slack resources, and refuses to judge progress by global metrics until the last weak link is repaired. Tell the team explicitly: "Activation work will not move revenue this quarter — it removes the cap so that next quarter's acquisition work can." + +**Excellence as a moat:** the same logic in reverse. When every link is matched and mutually adapted — IKEA's in-house flat-pack design, catalog, and out-of-town warehouse showrooms each presuppose the others — a rival copying any single link gains nothing, and copying all of them means becoming a different company. Matched chains are among the strongest isolating mechanisms available. + +**When to use:** when effort is everywhere and results are nowhere — and as a build target when you want advantage rivals cannot cherry-pick. + +## Design-Type Strategy + +Some strategies are choices among known positions; the most powerful are *designs* — premeditated configurations of resources and actions, like designing an aircraft rather than picking one from a catalog. Hannibal's victory at Cannae was not "fight harder"; it was a designed sequence — feigned retreat, enveloping cavalry, anticipation of Roman aggression — every piece presupposing the others. + +**The three marks of design:** premeditation (worked out in advance, not emergent improvisation), anticipation (built on others' predicted behavior), and coordination (parts configured to reinforce each other, accepting trade-offs a menu-chooser would refuse). + +**The performance/flexibility trade-off.** Tight integration extracts maximum performance from limited resources but resists change; loose, modular configurations sacrifice peak performance for adaptability. Choose tight design when stakes are high, resources are scarce, and the competitive window is now — a vertical AI product owning data pipeline, fine-tuned model, and workflow UI will beat an assembled API stack on quality, but will re-platform slower when models leap. Choose modularity when rich in resources or when uncertainty dominates. + +**When to use:** high-stakes plays where you must beat better-resourced rivals — design is how the weak beat the strong, and why second-rate strategies suffice for those with overwhelming advantage. + +## Focus + +Focus is a coordinated set of policies aimed at a narrow target, producing power that rivals serving everyone cannot match without wrecking their own economics. Crown Cork & Seal prospered in the "commodity" can business by configuring everything — plant location, spare capacity, technical service — around short runs and rush orders for smaller customers, and earned pricing power where larger rivals saw none. + +**Application discipline:** pick the segment where the incumbent's strengths are irrelevant or self-blocking; configure multiple policies (product, pricing, support, distribution) on it simultaneously — focus is the *coordination*, not just the narrowing; and verify the segment either values you enough to pay or leads somewhere larger. A startup "focused" on a segment it serves with the same generic product is narrow, not focused. + +## Using Advantage + +Advantage is rooted in asymmetry — a difference between you and rivals that translates into lower cost or higher willingness-to-pay. Two disciplines: + +**Advantage is positional, not general.** No company is simply "better"; it is advantaged in some contests and disadvantaged in others. And an advantage matters only at the *point of contention*: nobody cares about your costs except where you actually compete for a customer's decision. Strategy means steering competition toward the contests where your asymmetry decides. + +**An advantage must be used to be valuable.** Like a silver mine, an advantage you cannot extract more value from is sterile. Four ways to work it: + +1. **Deepen it** — widen the gap between value delivered and cost in your existing wedge (the default, most neglected move). +2. **Broaden it** — carry the underlying asymmetry to adjacent fields: proprietary job-cost data extends from dispatch software into benchmarking and insurance pricing; a beloved character franchise extends from films into parks and merchandise. +3. **Create demand** for what you are uniquely good at — grow the segment where your asymmetry decides. +4. **Strengthen isolating mechanisms** — the barriers that stop imitation from eroding returns: patents, brand and reputation, network effects, switching costs, tacit team know-how, exclusive relationships. If returns are good and undefended, your strategy's clock is running. + +**When to use:** whenever you already hold an asymmetry — and as a test of every proposed advantage: if it changes neither cost nor willingness-to-pay at a real point of contention, it is decoration. + +## Stacking Sources + +Real strategies stack two or three sources. The startup in [kernel.md](kernel.md) stacks concentration (one motion), a pivot point (time-to-first-value), and anticipation (rivals' enterprise distraction). The established platform stacks focus (mechanical trades), advantage (proprietary data), and de-entropy. When reviewing a strategy, name its sources of power explicitly; if you cannot name any, the strategy is effort dressed as insight. diff --git a/.agents/skills/grow-app/SKILL.md b/.agents/skills/grow-app/SKILL.md new file mode 100644 index 00000000..96a3eceb --- /dev/null +++ b/.agents/skills/grow-app/SKILL.md @@ -0,0 +1,232 @@ +--- +name: grow-app +description: 'Guided journey from an app people sign up for and then quietly abandon to a sealed retention engine with a habit loop, an activated first run, and one metric the whole team trusts. Orchestrates eight skills phase by phase - hooked-ux, improve-retention, continuous-discovery, lean-ux, inspired-product, lean-analytics, microinteractions, drive-motivation - asking the user questions at every decision point and recording results in the project docs/ folder (PRODUCT.md, METRICS.md, GROW-APP-PLAN.md) so the journey resumes across sessions. Use when the user wants to lift activation and retention, design a habit loop, fix a leaky onboarding funnel, or says ''users sign up then disappear''. Do not use to fix broken UX or performance that no engagement mechanic can paper over - run improve-app first; if there is no app yet, use create-app. For one framework in isolation, invoke that skill directly.' +license: MIT +metadata: + author: wondelai + version: "1.0.1" +--- + +# Grow an App + +Your app has users who sign up and then quietly disappear — cohorts decay, daily actives are flat, the activation funnel leaks where it always has, and nothing looks obviously broken. This journey seals the bucket: it turns first-time users into activated, then habitual, then would-miss-it users across eight interactive phases. The agent asks before every decision and records the outcome in `docs/`, so the work resumes across sessions instead of restarting. Growth here is an engineering and design problem, not a bigger ad budget. + +## Core Principle + +**Fix the leaky bucket before pouring in acquisition: habit, activation, and retention come before any growth spend.** This skill sequences the eight phases, asks every decision question, and records each choice in `docs/`. The constituent skills carry the method — invoke them rather than improvising their frameworks. + +## Journey Map + +| Phase | Skill | Question it answers | Artifact | +|---|---|---|---| +| 1 | hooked-ux | Why do users come back without us paying? | Extends docs/PRODUCT.md | +| 2 | improve-retention | Why don't new users reach the loop? | Extends docs/PRODUCT.md | +| 3 | continuous-discovery | What do our own users actually need? | Extends docs/PRODUCT.md + docs/CUSTOMER.md | +| 4 | lean-ux | Which bet is worth building? | Extends docs/EXPERIMENTS.md | +| 5 | inspired-product | Is the team building the right things? | Extends docs/PRODUCT.md | +| 6 | lean-analytics | Which single number tells the truth? | Creates docs/METRICS.md — sets the Rule 8 bar | +| 7 | microinteractions | Does it feel alive in the hand? | Extends docs/DESIGN.md | +| 8 | drive-motivation | Will engagement last, or curdle? | Extends docs/PRODUCT.md | + +Phases 1-2 seal the loop and the funnel; 3-5 steer with evidence; 6 is the instrument panel; 7-8 are the finish and the ethical backstop. Take the lean-analytics baseline (Phase 6) early — before the Phase 1-2 fixes land — so every change is read against a pre-change number, then keep updating it. Habit formation is slow: read Phase 1's success against the "5% rule" (a habit has formed when 5%+ of users return unprompted), not a single cohort. + +## Operating Rules + +1. **Resume first.** Before anything else, read `docs/GROW-APP-PLAN.md` and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted. +2. **Intake on first run only.** No tracker: run the Intake below, then create `docs/GROW-APP-PLAN.md` with every phase statused `pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason`. Done when the tracker exists and the user has confirmed the phase plan. +3. **Phase entry.** Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase `in-progress` on proceed. Done when the user chose. +4. **Skill invocation and fallback.** Invoke the phase's skill by its slug. If it is not available, offer: `npx skills add wondelai/skills/ --global`. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in. +5. **In-phase decisions.** Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect. +6. **Phase exit.** Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows `done`. +7. **Artifact discipline.** Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in `docs/`. Every recommendation lands as a checkbox or a table row with owner and priority. See [references/artifact-templates.md](references/artifact-templates.md) when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names. +8. **Retention before acquisition.** Acquisition-oriented phases — the optional cold-start-problem, contagious, and crossing-the-chasm, plus any paid-growth work — stay locked while activation and retention sit below the bar set at intake; unlock them only once the cohort curve clears that bar. Every habit loop and reward must pass the Manipulation Matrix: build only what the maker would use and honestly believes materially improves users. When a tactic needs manufactured anxiety or loss aversion, replace it with one built on real value. + +## Intake + +Run only on first start (no tracker). Ask: + +1. What does the app do, and what core action does a retained user repeat? (defines the Hook loop and the OMTM) +2. What are the current retention numbers — day-1/7/30 or week-4 cohorts? (sets the Rule 8 acquisition bar; feeds lean-analytics) +3. Where does the activation funnel leak, and what is the first-run flow? (gates improve-retention) +4. Solo/small team or a full product trio (PM, designer, engineer)? (scales continuous-discovery and inspired-product) +5. Is the app a network/marketplace product, and do engaged users fail to convert to revenue? (flags optional cold-start-problem / monetizing-innovation) +6. What analytics and instrumentation exist today? (gates lean-analytics and every experiment) +7. Is retention broken by UX or performance rather than missing engagement? (if yes, route to improve-app first) + +Skip heuristics: skip Phase 5 for a solo founder with no team to realign; defer Phase 7 until the loop and activation clear their bars; run Phase 3's cadence degraded if no user access exists yet. Then create the tracker from references/artifact-templates.md with every phase statused, and confirm the plan. + +Done when `docs/GROW-APP-PLAN.md` exists with every phase statused and the user has confirmed the plan. + +## Phases + +### Phase 1 — Design the habit loop that brings users back (hooked-ux) + +**Purpose:** Build the engine of return — a Hook loop strong enough that users come back on an internal trigger, not a paid notification. + +**Brief (fallback):** The Hook Model runs Trigger → Action → Variable Reward → Investment. Migrate external triggers (push, email) to internal ones (an emotion — boredom, FOMO, anxiety). Make the action trivially simple. Make the reward variable across tribe/hunt/self. Sequence investment *after* the reward so it raises switching cost and loads the next trigger. A loop with one weak phase stalls, not half-works. + +**Invoke:** `hooked-ux` with the core loop and how daily-active users return today. Ask it to (a) map the loop across all four phases, rate each 0-10, and name the weakest, and (b) design honest variable-reward concepts powered by data you already have, each checked against the Manipulation Matrix. + +**Decide with the user:** +- Which internal trigger (emotion) should pull users back — confirm one. +- Which single phase is weakest and gets the highest-leverage fix now — or defer if the loop is already forming (5%+ unprompted return). +- Which reward type to strengthen — tribe (social), hunt (resources), or self (mastery) — rejecting any concept that fails the Manipulation Matrix. + +**Artifact:** Extend docs/PRODUCT.md `## Hook Model` (trigger → action → variable reward → investment; weakest phase named). Update the tracker. + +**Done when:** PRODUCT.md names the internal trigger and all four phases, the weakest phase and its fix are recorded, onboarding is re-engineered so a new user completes one full Hook cycle in the first session, and the user picked the fix to ship. + +### Phase 2 — Fix activation by making the first action almost effortless (improve-retention) + +**Purpose:** Get new users to the loop by making the first meaningful action almost effortless. + +**Brief (fallback):** B=MAP — behavior fires only when Motivation, Ability, and a Prompt converge. Motivation is unreliable; raise Ability instead. Simplicity is capped by the *scarcest* of six resources: time, money, physical effort, mental effort, social deviance, non-routineness. Shrink the target to a Starter Step that delivers value in under 30s, anchor it to an existing routine, and celebrate the win immediately. + +**Invoke:** `improve-retention` with the real activation flow step by step and the day-1/7/30 drop-offs. Ask for a B=MAP friction audit rating all six Ability-Chain factors, the scarcest resource named, a Starter Step redesign, and event-based prompt rules. + +**Decide with the user:** +- Which is the scarcest Ability resource for the first action — fix that link first, not the obvious one. +- The Starter Step (tiniest valuable action) and its celebration moment. +- Which time-based prompts convert to event-based, dropping any that fail "would I appreciate this now?". + +**Artifact:** Extend docs/PRODUCT.md `## Activation & Retention Plan` (friction/moment | fix | owner | status). Update the tracker. + +**Done when:** the scarcest resource is named, the Starter Step, celebration, and prompt changes are rows with owners, each day-1/7/30 drop-off is mapped to its likely B=MAP failure, and the user approved the fix list. + +### Phase 3 — Run continuous discovery so you stop guessing (continuous-discovery) + +**Purpose:** Replace generic best-practice with a weekly stream of evidence about your own users. + +**Brief (fallback):** Aim for at least one customer touchpoint per week. Build an Opportunity Solution Tree: outcome at the top → customer opportunities (needs/pains in the customer's words) → candidate solutions/experiments. Never leap outcome→solution. Interviews are story-based ("tell me about the last time you…"), captured as one-page snapshots. Test the riskiest leap-of-faith assumption first, cheaply. + +**Invoke:** `continuous-discovery` with the retention outcome and known churn patterns. Ask for an Opportunity Solution Tree, a current-state experience map of how churned users try to succeed today, a weekly story-based interview snapshot template, and an assumption map for the next planned feature. + +**Decide with the user:** +- The single outcome at the top of the tree. +- Which two or three opportunities to pursue first. +- The weekly cadence and recruitment mechanism the team can actually sustain — set it now or run degraded. +- The riskiest leap-of-faith assumption inside the next feature (desirability, viability, feasibility, usability) and the cheapest test for it. + +**Artifact:** Extend docs/PRODUCT.md `## Opportunity Solution Tree Notes`, `## Outcome Roadmap` (outcome/problem | job served | priority | status), and `## Discovery Cadence`; extend docs/CUSTOMER.md `## Interview Evidence` (date | who | facts | commitment). Update the tracker. + +**Done when:** the tree's outcome and top opportunities are recorded, the cadence is scheduled, the first interview snapshot template exists, and the riskiest assumption has a cheap test designed. + +### Phase 4 — Replace debate with cheap experiments (lean-ux) + +**Purpose:** Turn opportunities into falsifiable bets settled by behavior, not meetings. + +**Brief (fallback):** Outcomes over outputs — value is the behavior change, not the deliverable. Write a hypothesis: "We believe [outcome] will happen if [persona] achieves [action] with [feature]," with the metric and threshold committed *before* the test. Match fidelity to risk (a paper prototype with five users finds ~85% of usability issues); reserve A/B tests for tuning a proven concept. When invalidated, remove from the backlog — don't defer. + +**Invoke:** `lean-ux` with the biggest current design debate or a top discovery opportunity. Ask for three hypothesis statements in the standard format, the lowest-fidelity experiment that could validate the top one, and its pre-committed metric, threshold, and timebox. + +**Decide with the user:** +- Which hypothesis to test first. +- The experiment fidelity — the lowest that answers the actual question. +- The pass/fail line and what leaves the backlog if it fails. + +**Artifact:** Extend docs/EXPERIMENTS.md `## Experiment Cards` (hypothesis, type, primary metric + threshold, guardrail, decision rule) and `## Experiment Backlog` (idea | ICE | status). Update the tracker. + +**Done when:** at least one experiment card has a pre-committed threshold and decision rule, the backlog is triaged, and the user chose the first test. + +### Phase 5 — Build the right things with an empowered team (inspired-product) + +**Purpose:** Move the team from feature factory to outcome ownership — problems to solve, not features to ship. + +**Brief (fallback):** Empowered teams get problems, not backlogs, and answer for outcomes. Dual-track: discovery (what's worth building — addressing value, usability, feasibility, viability) runs continuously alongside delivery. Expect 10-20 discovery iterations per shipped feature. Give the team a product vision and an outcome-based roadmap so it can decide autonomously. + +**Invoke:** `inspired-product` with the top three backlog requests and the current roadmap. Ask for an opportunity assessment of each (objective, target user, problem, success measure, alternatives) and a one-paragraph vision plus a quarter of outcome-based roadmap items. + +**Decide with the user:** +- Which backlog request has the strongest evidence — and which to kill before it reaches a sprint. +- The one-paragraph product vision. +- Whether the roadmap is reframed as problems + key results rather than dated features. + +**Artifact:** Extend docs/PRODUCT.md `## Vision` and `## Outcome Roadmap` (outcome/problem | job served | priority | status). Update the tracker. + +**Done when:** the vision paragraph exists, each of the three requests has a build/kill verdict, and the roadmap rows are outcomes, not features. + +### Phase 6 — Measure the one number that actually matters (lean-analytics) + +**Purpose:** Point the whole team at the One Metric That Matters and expose the vanity metrics hiding the decay. + +**Brief (fallback):** A good metric is comparative, a ratio/rate (not a cumulative total), and behavior-changing. Business model dictates which metrics matter; stage dictates sequencing (Empathy → Stickiness → Virality → Revenue → Scale). Weak retention = Stickiness stage, so retention is the OMTM — working a later stage first is the canonical mistake. Draw a line in the sand (target, date, miss response), pair the OMTM with a counter-metric, and cohort the data. + +**Invoke:** `lean-analytics` with the current dashboard/metrics and the business model. Ask it to flag vanity metrics, pick the Stickiness-stage OMTM plus a counter-metric, design a one-screen dashboard (OMTM big, ≤6 supporting), and a cohorted retention view. + +**Decide with the user:** +- The OMTM and its counter-metric. +- The line in the sand — target, date, pre-committed miss response. +- Which current metrics are retired as vanity. + +**Artifact:** Create docs/METRICS.md with `## Stage & One Metric That Matters`, `## KPI Definitions`, `## Baselines & Targets`, `## Funnel`, and `## Cohort Notes`. Update the tracker. + +**Done when:** METRICS.md names the OMTM + counter-metric, records the line in the sand with a date, lists cohorted baselines, the vanity metrics are marked retired, the one-screen dashboard is specified, and the retention bar for the Rule 8 acquisition gate is set. + +### Phase 7 — Polish the micro-moments that make it feel alive (microinteractions) + +**Purpose:** Close the gap between an app people tolerate and one they love, in the moments they touch daily. + +**Brief (fallback):** Every microinteraction has Trigger → Rules → Feedback → Loops & Modes. Feedback is immediate (<100ms for direct manipulation) and proportionate; animate the element the user touched over a separate toast. Map every state: empty, loading, partial, error, disabled, double-tap. Invest in one or two signature moments that pass the removal test; use long loops to retire hints for power users. + +**Invoke:** `microinteractions` with the five most-used interactions. Ask for a Trigger/Rules/Feedback/Loops audit of each, the sub-100ms feedback and missing edge-case states, and one signature moment implemented in real code. + +**Decide with the user:** +- Which five interactions to audit. +- Which one becomes the signature moment (removal test applied). +- Which edge-case states to implement first. + +**Artifact:** Extend docs/DESIGN.md `## Microinteraction Inventory` (interaction | trigger/rules/feedback/loops | fix | status). Update the tracker. + +**Done when:** the five interactions are in the inventory with their missing states and fixes, the signature moment is chosen, and each fix has a status. + +### Phase 8 — Sustain engagement with intrinsic motivation (drive-motivation) + +**Purpose:** Keep the loops from curdling — engagement that runs on Autonomy, Mastery, and Purpose instead of exploitation. + +**Brief (fallback):** For any task needing cognitive effort, "if-then" rewards crush intrinsic motivation. Lasting engagement is Autonomy (choice over what/when/how/with whom), Mastery (visible progress, flow-calibrated challenge), and Purpose (why it matters). Autonomy killers: forced tutorials, unskippable steps, mandatory notifications. Reserve rewards for meaningful milestones; prefer "now-that" recognition over "if-then" bargains. + +**Invoke:** `drive-motivation` with the app's gamification, streaks, points, and notification patterns. Ask for an AMP audit rated 0-10, every autonomy violation flagged, the point at which streaks tipped into loss aversion, and a progression redesign around real mastery and purpose. + +**Decide with the user:** +- Which autonomy violations to remove (forced/unskippable steps). +- Which "if-then" rewards convert to "now-that" recognition. +- Whether any streak/points mechanic exploits loss aversion and must change. + +**Artifact:** Extend docs/PRODUCT.md `## Activation & Retention Plan` with AMP-audit rows (violation/finding | fix | owner | status). Update the tracker. + +**Done when:** the AMP score and every autonomy violation are recorded, the reward/streak fixes are rows with owners, and the loops pass the Manipulation Matrix from Rule 8. + +## Optional Phases + +| Skill | Add when | Artifact | +|---|---|---| +| cold-start-problem | the app is a network or marketplace product | Extends docs/PRODUCT.md | +| monetizing-innovation | engaged users do not translate into revenue | Extends docs/OFFER.md | +| contagious | users love the app but never mention it | Extends docs/MARKETING.md | +| crossing-the-chasm | growth stalls at the early-adopter boundary | Extends docs/STRATEGY.md | +| jobs-to-be-done | usage patterns say the app is hired for a different job | Extends docs/CUSTOMER.md | + +Optional phases follow the same operating rules; insert where the Add-when condition first becomes true. The acquisition-leaning ones — cold-start-problem, contagious, crossing-the-chasm — stay locked behind Rule 8 until retention clears the bar. + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Buying growth before fixing retention | Pass the Stickiness gate (a flattening cohort curve) before any acquisition spend; keep acquisition phases locked per Rule 8. | +| Relying on external triggers forever | Migrate to an internal trigger via hooked-ux; treat notifications as scaffolding, not the load-bearing wall. | +| Optimizing the wrong Ability-Chain link | Rate all six factors in improve-retention and fix the scarcest resource, not the most obvious one. | +| Jumping from outcome straight to solution | Build the Opportunity Solution Tree in continuous-discovery first; the obvious feature is often the worst of five. | +| Measuring outputs, not outcomes | Instrument every release; in lean-ux and inspired-product, success is a change in user behavior, not stories shipped. | +| Gamifying with points for everything | Reserve rewards for meaningful milestones and run the drive-motivation AMP audit; "if-then" rewards crowd out your power users. | + +## Completing the Journey + +- [ ] PRODUCT.md holds a Hook loop with the weakest phase fixed, an activation Starter Step, a living Opportunity Solution Tree, and an AMP-clean engagement design. +- [ ] METRICS.md names the Stickiness-stage OMTM plus a counter-metric with a line in the sand (target, date, miss response). +- [ ] At least one lean-ux experiment has resolved with a recorded verdict, and invalidated ideas are out of the backlog. +- [ ] The retention bar set at intake is met — or the remaining gap is quantified — before any acquisition phase runs. + +Close the tracker: every phase `done` or `skipped`, with Next Actions carried into PRODUCT.md, METRICS.md, and EXPERIMENTS.md. Then route forward: + +- When engagement mechanics cannot fix a product held back by broken UX or performance, continue with `improve-app`. +- When the app is sticking and the business around it must keep pace — revenue, channels, operations — continue with `grow-business`. diff --git a/.agents/skills/grow-app/references/artifact-templates.md b/.agents/skills/grow-app/references/artifact-templates.md new file mode 100644 index 00000000..2d29d23e --- /dev/null +++ b/.agents/skills/grow-app/references/artifact-templates.md @@ -0,0 +1,89 @@ +# Artifact templates — grow-app + +Skeletons this metaskill creates in the user's docs/ folder. Extend-only artifacts (CUSTOMER.md, EXPERIMENTS.md, DESIGN.md, OFFER.md, and the optional MARKETING.md / STRATEGY.md) are governed by the section headings named in each phase — read the existing file, add or update your sections, preserve everyone else's. The two skeletons below (METRICS.md, PRODUCT.md) are the files grow-app most often creates from scratch; copy them verbatim. + +## Tracker: docs/GROW-APP-PLAN.md + +Create this on first run (Intake). Phase rows are pre-filled; fill Status and Date as the journey advances. + +```markdown +# Grow an App Plan + +## Context +Intake answers, date started, project specifics. + +## Phase Status +| Phase | Skill | Status | Artifact | Date | +|---|---|---|---|---| +| 1. Habit loop | hooked-ux | pending | PRODUCT.md | | +| 2. Activation | improve-retention | pending | PRODUCT.md | | +| 3. Continuous discovery | continuous-discovery | pending | PRODUCT.md, CUSTOMER.md | | +| 4. Lean UX experiments | lean-ux | pending | EXPERIMENTS.md | | +| 5. Empowered team | inspired-product | pending | PRODUCT.md | | +| 6. One metric that matters | lean-analytics | pending | METRICS.md | | +| 7. Microinteractions | microinteractions | pending | DESIGN.md | | +| 8. Intrinsic motivation | drive-motivation | pending | PRODUCT.md | | +Statuses: pending · in-progress · awaiting-evidence · done · deferred: · skipped: + +## Key Decisions +| Date | Phase | Decision | Rationale | +|---|---|---|---| + +## Next Actions +- [ ] action (owner, due) +``` + +## docs/METRICS.md + +Created in Phase 6 (lean-analytics). Creates: improve-business, grow-app. + +```markdown +# Metrics + +## Stage & One Metric That Matters +OMTM · counter-metric · why now. + +## KPI Definitions +| Metric | Definition | Actionable ratio? | Owner | +|---|---|---|---| + +## Baselines & Targets +| Metric | Baseline (date) | Target | Line in the sand (miss response) | +|---|---|---|---| + +## Funnel +| Stage | Conversion | Benchmark | Bottleneck? | +|---|---|---|---| + +## Cohort Notes +``` + +## docs/PRODUCT.md + +Extended across Phases 1, 2, 3, 5, and 8; create it here if the project has no PRODUCT.md yet. Creates: create-app, create-business. Extends: grow-app, improve-app. + +```markdown +# Product + +## Vision +One paragraph. + +## MVP Definition +Type, scope, what it deliberately excludes. + +## Outcome Roadmap +| Outcome / problem | Job served | Priority | Status | +|---|---|---|---| + +## Opportunity Solution Tree Notes + +## Hook Model +Trigger → Action → Variable reward → Investment; weakest phase. + +## Activation & Retention Plan +| Friction / moment | Fix | Owner | Status | +|---|---|---|---| + +## Discovery Cadence +Weekly touchpoint plan. +``` diff --git a/.agents/skills/grow-business/SKILL.md b/.agents/skills/grow-business/SKILL.md new file mode 100644 index 00000000..3b1ebeae --- /dev/null +++ b/.agents/skills/grow-business/SKILL.md @@ -0,0 +1,231 @@ +--- +name: grow-business +description: 'Guided journey from a business with lucky months to a repeatable growth engine that produces a forecast. Orchestrates nine skills phase by phase - one-page-marketing, hundred-million-offers, predictable-revenue, contagious, influence-psychology, crossing-the-chasm, cold-start-problem, lean-analytics, negotiation - asking the user questions at every decision point and recording results in the project docs/ folder (MARKETING.md, OFFER.md, METRICS.md, GROW-BUSINESS-PLAN.md) so the journey resumes across sessions. Use when the user wants to build a marketing and sales system, manufacture predictable pipeline, engineer word-of-mouth and referrals, or says ''revenue is real but lumpy and I need growth that repeats''. If the offer, retention, or operations underneath are broken, run improve-business first; with no paying customers yet, start with create-business; when the product itself must carry the growth loops, use grow-app. For one framework in isolation, invoke that skill directly.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# Grow a Business + +You already have the hard part: a product people pay for. Revenue is real but lumpy — a good month came from a conference you happened to attend or a referral that happened to land, and none of it repeats on demand. This journey turns that traction into a repeatable growth engine across nine phases: a marketing map, an irresistible offer, an outbound motion, engineered word-of-mouth, persuasion on every surface, a mainstream go-to-market, a compounding network, one honest metric, and the discipline to hold price. It is interactive — the agent asks before every decision — and resumable, because every decision and asset is recorded in `docs/`. Install the whole stack at once with `npx skills add wondelai/skills --all --global`, or let each phase pull its skill on demand. + +## Core Principle + +**Build a repeatable growth engine: each phase produces an asset the next phase consumes — offer feeds pipeline, pipeline feeds word-of-mouth, metrics keep it honest.** The order is load-bearing; a skipped Phase 1 leaves the later phases with no shared target. This skill sequences the phases, asks the decision questions, and records the answers. The constituent skills carry the method — invoke them rather than improvising their frameworks. + +The offer comes before every channel on purpose: sending traffic to a weak offer is the most expensive mistake in growth, so Phase 2 is fixed before outbound, virality, or repositioning turn on. + +## Journey Map + +| Phase | Skill | Question it answers | Artifact | +|---|---|---|---| +| 1 | one-page-marketing | Which niche, and which square of the machine is empty? | Creates docs/MARKETING.md | +| 2 | hundred-million-offers | Why should they buy this instead of the alternative? | Extends docs/OFFER.md | +| 3 | predictable-revenue | How do we manufacture pipeline on demand? | Extends docs/MARKETING.md | +| 4 | contagious | Why would anyone share this? | Extends docs/MARKETING.md | +| 5 | influence-psychology | Why do they say yes on the page? | Extends docs/OFFER.md | +| 6 | crossing-the-chasm | How do we reach the mainstream buyer? | Extends docs/STRATEGY.md + docs/CUSTOMER.md | +| 7 | cold-start-problem | How does the network do the acquiring? | Extends docs/MARKETING.md | +| 8 | lean-analytics | Which one number tells us it is working? | Extends docs/METRICS.md | +| 9 | negotiation | How do we capture the value instead of discounting it? | Extends docs/OFFER.md | + +Four of the nine phases write to MARKETING.md — the flagship this journey creates. OFFER.md, STRATEGY.md, METRICS.md, and CUSTOMER.md are extended, so files a prior create-business journey already owns are reused and augmented, never overwritten. + +The tracker `docs/GROW-BUSINESS-PLAN.md` is private to this journey and never shared with another; it is the resume point that carries state across sessions. + +## Operating Rules + +1. **Resume first.** Before anything else, read `docs/GROW-BUSINESS-PLAN.md` and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted. +2. **Intake on first run only.** No tracker: run the Intake below, then create `docs/GROW-BUSINESS-PLAN.md` with every phase statused `pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason`. Done when the tracker exists and the user has confirmed the phase plan. +3. **Phase entry.** Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase `in-progress` on proceed. Done when the user chose. +4. **Skill invocation and fallback.** Invoke the phase's skill by its slug. If it is not available, offer: `npx skills add wondelai/skills/ --global`. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in. +5. **In-phase decisions.** Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect. +6. **Phase exit.** Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows `done`. +7. **Artifact discipline.** Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in `docs/`. Every recommendation lands as a checkbox or a table row with owner and priority. See [references/artifact-templates.md](references/artifact-templates.md) when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names. +8. **Every scarcity claim, testimonial, and guarantee must be true, and referral incentives must reward real value delivered.** When a tactic needs inventing evidence, replace it with a tactic that uses evidence you have. + +## Intake + +Ask these before creating the tracker: + +1. Current revenue, customer count, and what "lumpy" looks like month to month (baselines feed Phase 8; volume sizes the Phase 3 pipeline math). +2. Where does new business come from today, and which single channel carries most of it (reveals the empty marketing square in Phase 1; over-reliance is your risk). +3. Which segments could you focus on (feeds the Phase 1 PVP Index and the Phase 6 beachhead). +4. Current offer and price — and was pricing ever tested against willingness to pay (gates Phase 2; if never tested, add the monetizing-innovation optional phase). +5. Does the product get better as more people or teams use it — shared workspaces, referrals, a directory (gates Phase 7; skip it if there is no network dimension). +6. Existing `docs/` artifacts from a prior journey — CUSTOMER.md, POSITIONING.md, STRATEGY.md — to read and reuse (avoids re-deriving; sets extend vs create). +7. The single most painful growth constraint right now (lets you reorder — if the offer is the constraint, lead with Phase 2). + +Skip heuristics: skip Phase 3 when the motion is pure self-serve and no sales-assisted motion is wanted; skip Phase 6 when you already sell to the mainstream pragmatist majority; skip Phase 7 when the product has no multiplayer or network dimension; skip Phase 9 when pricing is fixed self-serve checkout with no negotiated deals. + +Then create `docs/GROW-BUSINESS-PLAN.md` from the template and confirm the plan. Done when `docs/GROW-BUSINESS-PLAN.md` exists with every phase statused and the user has confirmed the plan. + +## Phases + +Run the phases in order unless intake reordered them. Each phase's Invoke reads what earlier phases wrote to `docs/`; if an upstream phase was skipped, its reader falls back to the intake facts and flags the missing input rather than inventing it. + +### Phase 1 — Install the marketing operating system (one-page-marketing) + +**Purpose:** Lay out the whole marketing machine on one page so the missing square is visible before spending on any tactic. + +**Brief (fallback):** A 3x3 grid across the customer journey — Before (target market, message, media), During (capture leads, nurture, convert), After (deliver the experience, increase lifetime value, orchestrate referrals). Marketing is a process, not an event; random tactics fail because they fill one square while eight stay empty. Score 0-10 on how completely and specifically all nine are filled. Run the PVP Index (Personal fulfillment, Value to market, Profitability) to pick one niche to dominate. + +**Invoke:** `one-page-marketing` with the intake facts (revenue, customers, current channels, candidate segments). Ask for (a) all nine squares filled and scored out of 10 with the single weakest square plus three fixes, and (b) a PVP Index across the candidate segments recommending one niche and writing its avatar. + +**Decide with the user:** Which niche to dominate first (the PVP winner — this becomes the Phase 6 beachhead candidate)? Which weakest square to attack first? Confirm the avatar is one named persona, not "everyone". + +**Artifact:** Create docs/MARKETING.md with `## Target Market & Avatar` (PVP niche + avatar), `## Before / During / After Grid` (phase | square | current state | plan), and `## Channels`. Update the tracker. + +**Done when:** MARKETING.md exists, the grid is filled and scored, the PVP niche and avatar are recorded, and the user chose the niche and the weakest square. + +### Phase 2 — Make the offer impossible to refuse (hundred-million-offers) + +**Purpose:** Turn the core product into a Grand Slam Offer so conversion stops being a fight before any traffic is turned on. + +**Brief (fallback):** Value = (Dream Outcome x Perceived Likelihood) / (Time Delay x Effort and Sacrifice) — maximize the top, minimize the bottom. Assemble core product + named bonuses that each kill one objection + a risk-reversing guarantee + ethical (real) scarcity, until the stack dwarfs the price. Name it with MAGIC (Magnetic reason, Avatar, Goal, time Indicator, Container). Premium pricing attracts committed customers who churn less. + +**Invoke:** `hundred-million-offers` with the current offer and price from intake (and docs/OFFER.md if it exists). Ask for a score out of 10, the weakest Value-Equation lever, three objection-killing bonuses with defensible dollar values, a guarantee type, and a MAGIC name. + +**Decide with the user:** Is "too expensive" a price problem or a value-construction problem? Raise the price and add a done-for-you bonus, or hold? Which three bonuses ship? + +**Artifact:** Create or extend docs/OFFER.md: `## Offer Stack` (element | description | honest value | objection it kills) and `## Price Metric`. Update the tracker. + +**Done when:** OFFER.md holds a scored Grand Slam Offer with named bonuses, a guarantee, real scarcity, and a MAGIC name, and the pricing decision is recorded. + +### Phase 3 — Manufacture pipeline with outbound (predictable-revenue) + +**Purpose:** Build a sales motion you can throttle — turn up to make deals, turn down to pause — instead of waiting for luck. + +**Brief (fallback):** Lead types: Seeds (referrals — highest conversion, slow to build), Nets (inbound — medium), Spears (outbound — predictable, you control volume). Most under-invest in Spears. Specialize roles: SDRs prospect, AEs close, CSMs retain — never the same person prospecting and closing. Cold Calling 2.0: email above the decision-maker for a referral in, no pitch; response runs 9-15% vs 1-3%. Qualify with ANUM (Authority, Need, Urgency, Money). Run pipeline math backward from the revenue goal. + +**Invoke:** `predictable-revenue` with the revenue goal, average deal, and win rate from intake, plus the USP and niche from MARKETING.md. Ask for (a) backward pipeline math to emails and SDR count, (b) a four-touch Cold Calling 2.0 sequence, and (c) an ANUM SDR-to-AE handoff. + +**Decide with the user:** Is the revenue goal reachable at current conversion, or adjust the goal or hire? Specialize roles now or stay generalist a while longer? What Seeds/Nets/Spears mix to target? + +**Artifact:** Extend docs/MARKETING.md: `## Outbound Process` (roles, sequences, ANUM qualification, handoff format) with the pipeline math. Update the tracker. + +**Done when:** MARKETING.md holds the pipeline math, the cold-email sequence, and the qualification-plus-handoff, and the goal, hiring, and role decisions are recorded. + +### Phase 4 — Engineer word-of-mouth (contagious) + +**Purpose:** Manufacture Seeds on purpose — design shareability into a feature or campaign instead of hoping referrals happen. + +**Brief (fallback):** STEPPS — Social Currency (sharing makes them look good), Triggers (everyday cues that keep you top-of-mind), Emotion (high-arousal: awe, anger, excitement drive sharing; contentment suppresses it), Public (visible usage others imitate), Practical Value (useful enough to pass on), Stories (a narrative retold with the brand baked in). Only ~7% of word-of-mouth is online. Trojan Horse test: if the story survives without your brand named, it failed. Triggers and Practical Value are usually highest-leverage for an existing business. + +**Invoke:** `contagious` with a candidate campaign, feature, or the quarterly customer email, plus the niche and avatar from MARKETING.md. Ask for a STEPPS audit scored out of 10 and a redesign that engineers the two weakest-but-highest-leverage drivers. + +**Decide with the user:** Which asset to engineer first? Which one or two STEPPS levers to strengthen (Triggers and Practical Value usually win)? + +**Artifact:** Extend docs/MARKETING.md: `## Word-of-Mouth (STEPPS)` (lever | idea | status), including the chosen Trigger and a Trojan-Horse story that passes the retell test. Update the tracker. + +**Done when:** MARKETING.md holds a STEPPS table with at least one engineered Trigger and a brand-embedded story, and the user chose the asset and levers. + +### Phase 5 — Build persuasion into every surface (influence-psychology) + +**Purpose:** Lift conversion on the surfaces that already have traffic — pricing page, testimonials, checkout — without spending more on acquisition. + +**Brief (fallback):** Seven principles layer: Reciprocity, Commitment and Consistency, Social Proof, Authority, Liking, Scarcity, Unity. Specifics matter: exact numbers beat vague ("2,347 firms" beats "thousands"), negative social proof backfires, admitting a weakness raises authority, newly-scarce beats always-scarce (loss framing). Persuasion helps people see value they would appreciate anyway; manipulation tricks them against their interest — the line the skill enforces. + +**Invoke:** `influence-psychology` with the pricing page, testimonial block, or checkout flow, plus the offer from docs/OFFER.md. Ask for an audit naming which of the seven principles are present and missing, a score out of 10, rewritten weak spots, and an ethics check on every tactic. + +**Decide with the user:** Which surface to fix first? Which principles to add where? Confirm every scarcity and proof claim is real — a tactic that fails the ethics check gets replaced with one using evidence you have, never faked. + +**Artifact:** Extend docs/OFFER.md: under `## Offer Stack` add `### Persuasion Audit` (principle | present? | fix) and `### Proof & Social Proof` (concrete testimonials + placement where objections peak). Update the tracker. + +**Done when:** OFFER.md holds a scored persuasion audit, rewritten proof placed where objections peak, and every claim verified true. + +### Phase 6 — Cross the chasm to the mainstream (crossing-the-chasm) + +**Purpose:** Make the jump from enthusiasts to pragmatists — target one beachhead, assemble the whole product, and reposition for "it just works." + +**Brief (fallback):** Early adopters (visionaries) tolerate rough edges and buy the vision; the early majority (pragmatists) want proven solutions, references from peers, and a complete product. The D-Day strategy: dominate one narrow beachhead — urgent expensive pain, reachable channel, members who talk to each other — then expand from strength. Assemble the whole product (integrations, onboarding, migration, support), partnering for gaps. "Revolutionary" becomes "proven solution for [problem]"; "be first" becomes "join 500 firms like yours." + +**Invoke:** `crossing-the-chasm` with the PVP niche from MARKETING.md as the beachhead candidate. Ask for a go-to-market score out of 10, a whole-product gap analysis, and positioning rewritten for pragmatists using Moore's formula. + +**Decide with the user:** Confirm the beachhead (urgent pain, reachable channel, members who talk to each other)? Which whole-product gaps to build vs partner for? Adopt the pragmatist repositioning? + +**Artifact:** Extend docs/STRATEGY.md: `## Beachhead` and `## Whole-Product Checklist` (- [ ] gap (owner, priority)); and extend docs/CUSTOMER.md: `## Segments & Best-Fit Customer` with the pragmatist beachhead. Update the tracker. + +**Done when:** STRATEGY.md names the beachhead and a checklisted whole-product gap list, CUSTOMER.md records the pragmatist segment, and the build/partner and repositioning decisions are recorded. + +### Phase 7 — Turn customers into a compounding network (cold-start-problem) + +**Purpose:** Formalize the referral square and word-of-mouth into a self-reinforcing loop where the network does the acquiring. + +**Brief (fallback):** Network effects are a liability before an asset; they grow by saturating one tiny complete network at a time, not by launching broadly. Atomic network: the smallest self-sustaining unit (one firm, one city) — over-deliver until dense, then replicate with a playbook. The hard side: the minority who do the disproportionate work and are hardest to keep — build for them first. Tipping playbook: invite-only mechanics and two-sided referral incentives import each new user along an existing relationship. + +**Invoke:** `cold-start-problem` with the product's multiplayer or shared dimension and the referral square from MARKETING.md. Ask for a defined atomic network, the hard side and what retains them, and a two-sided referral/invite loop with real (never faked) incentives, scored out of 10. + +**Decide with the user:** Which atomic-network unit (firm / city / practice area)? Who is the hard side and why do they stay? What real incentive does each side of the referral get? + +**Artifact:** Extend docs/MARKETING.md: `## Referral & Invite Mechanics` with the atomic network, the hard side, and the two-sided loop. Update the tracker. + +**Done when:** MARKETING.md holds a defined atomic network, the hard side, and a two-sided referral loop with real incentives, and density (not signup) metrics are named for Phase 8. + +### Phase 8 — Point everything at the one metric that matters (lean-analytics) + +**Purpose:** Cut the dashboard to the single number that says whether the riskiest part of the business is working, and let it gate every experiment. + +**Brief (fallback):** A good metric is comparative, a ratio or rate (not an ever-growing total), and behavior-changing — if it will not change a decision, stop measuring it. Cumulative up-and-to-the-right charts are the vanity tell. OMTM = intersection of business model (SaaS: churn, MRR, LTV:CAC, time-to-value) and stage (Empathy, Stickiness, Virality, Revenue, Scale). Pair it with a counter-metric so it cannot be gamed; draw a line in the sand — target, date, pre-committed miss-response. Cohort and segment, because blended averages hide the truth. + +**Invoke:** `lean-analytics` with the current metric list, business model, and stage. Ask for which metrics are vanity, the OMTM derived from model and stage, a counter-metric, and a one-screen dashboard (OMTM big, 4-6 supporting metrics small). + +**Decide with the user:** Which stage are we in? What is the OMTM and its counter-metric? What line in the sand — target number, date, and what we do if we miss? + +**Artifact:** Create or extend docs/METRICS.md: `## Stage & One Metric That Matters`, `## KPI Definitions`, `## Baselines & Targets`, `## Funnel`, and `## Cohort Notes`. Update the tracker. + +**Done when:** METRICS.md names the OMTM, its counter-metric, the line in the sand, and a cohorted funnel, and vanity metrics are flagged. + +### Phase 9 — Stop discounting, capture the value you create (negotiation) + +**Purpose:** Hold price in high-stakes conversations so the value the engine built lands in the bank instead of being discounted away. + +**Brief (fallback):** The path to yes runs through empathy and being understood, not logic or compromise — and never split the difference: no deal beats a bad deal, because a pressured discount trains every future customer to ask. Tactical empathy and labeling name the other side's concern first; calibrated questions ("how am I supposed to do that at that price?") make them solve your problem; the accusation audit preempts objections; the Ackerman method holds price in decreasing increments to precise non-round numbers, closing with a non-monetary concession. + +**Invoke:** `negotiation` with a specific upcoming high-stakes conversation (a renewal at risk, a procurement squeeze, an enterprise deal). Ask for an accusation audit, five calibrated questions, an Ackerman plan (target, decreasing increments, non-monetary concession), and Black-Swan hypotheses. + +**Decide with the user:** Which conversation to prepare? What is the Ackerman target and the walk-away? Which non-monetary concessions can substitute for a discount? + +**Artifact:** Extend docs/OFFER.md: under `## Price Metric` add `### Price-Holding Playbook` (accusation audit, calibrated questions, Ackerman plan). Update the tracker. + +**Done when:** OFFER.md holds a reusable price-holding playbook, the next negotiation is prepped, and the target, walk-away, and concession list are recorded. + +## Optional Phases + +| Skill | Add when | Artifact | +|---|---|---| +| monetizing-innovation | pricing was never tested against willingness to pay | Extends docs/OFFER.md | +| good-strategy-bad-strategy | growth efforts scatter because there is no kernel | Extends docs/STRATEGY.md | +| traction-eos | execution rhythm cannot keep up with growth plans | Extends docs/OPERATIONS.md | +| scorecard-marketing | lead generation needs a quiz or assessment funnel | Extends docs/MARKETING.md | +| made-to-stick | the referral message is forgettable | Extends docs/POSITIONING.md | + +Optional phases follow the same operating rules; insert where the Add-when condition first becomes true. + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Optimizing the funnel before fixing the offer | Run Phase 2 (`hundred-million-offers`) against pricing before touching the funnel — the offer is the bigger lever. | +| Treating the nine skills as a buffet | Keep the order; Phase 1 sets the shared target every later phase reads (PVP niche → beachhead, USP → cold email, referral square → network loop). | +| Marketing to pragmatists like early adopters | Reframe as proven evolution via Phase 6 (`crossing-the-chasm`) — "proven solution", "join 500 firms", not "revolutionary". | +| Faking scarcity, social proof, or guarantees | Use real inventory, real numbers, real deadlines; the frameworks work without the fake version (Operating Rule 8). | +| Celebrating vanity metrics | Watch the one ratio that matters — Phase 8 (`lean-analytics`) flags cumulative up-and-to-the-right charts as decoration. | +| Building outbound on a leaky bucket | Let Phase 8's stickiness metric gate acquisition spend; if retention is broken, run improve-business first. | + +## Completing the Journey + +Exit checklist: + +- [ ] MARKETING.md: nine squares filled and scored, with the outbound process, STEPPS levers, and a two-sided referral loop +- [ ] OFFER.md: a scored Grand Slam Offer, a persuasion audit, and the price-holding playbook +- [ ] STRATEGY.md names a beachhead with a whole-product checklist; CUSTOMER.md records the pragmatist segment +- [ ] METRICS.md names the OMTM, its counter-metric, and the line in the sand +- [ ] GROW-BUSINESS-PLAN.md: every phase `done` or `skipped: reason`, with Key Decisions logged + +Close the tracker: every phase `done` or `skipped: reason`, and Next Actions carried into the artifacts as owned checkboxes. Growth without retention is a leaky bucket — before pouring more pipeline in, confirm Phase 8's stickiness metric is holding. Then route forward: + +- When growth stalls because the fundamentals underneath it are broken — retention, churn, operational drag — continue with `improve-business`. +- When the product itself must carry the growth loops — in-app referrals, network features, instrumentation — continue with `grow-app`. diff --git a/.agents/skills/grow-business/references/artifact-templates.md b/.agents/skills/grow-business/references/artifact-templates.md new file mode 100644 index 00000000..5a6204d9 --- /dev/null +++ b/.agents/skills/grow-business/references/artifact-templates.md @@ -0,0 +1,61 @@ +# Artifact templates — grow-business + +Skeletons this metaskill creates in the user's `docs/` folder. Extend-only artifacts (OFFER.md, STRATEGY.md, METRICS.md, CUSTOMER.md) are governed by the section headings named in each phase — read the file, add or update your sections, preserve everyone else's. Only the tracker and MARKETING.md (created by this journey) have full skeletons below. + +## docs/GROW-BUSINESS-PLAN.md (the tracker) + +```markdown +# Grow a Business Plan + +## Context +Intake answers, date started, project specifics. + +## Phase Status +| Phase | Skill | Status | Artifact | Date | +|---|---|---|---|---| +| 1. Marketing operating system | one-page-marketing | pending | MARKETING.md | | +| 2. Grand Slam Offer | hundred-million-offers | pending | OFFER.md | | +| 3. Outbound pipeline | predictable-revenue | pending | MARKETING.md | | +| 4. Word-of-mouth | contagious | pending | MARKETING.md | | +| 5. Persuasion | influence-psychology | pending | OFFER.md | | +| 6. Cross the chasm | crossing-the-chasm | pending | STRATEGY.md, CUSTOMER.md | | +| 7. Compounding network | cold-start-problem | pending | MARKETING.md | | +| 8. One metric that matters | lean-analytics | pending | METRICS.md | | +| 9. Hold the price | negotiation | pending | OFFER.md | | +Statuses: pending · in-progress · awaiting-evidence · done · deferred: · skipped: + +## Key Decisions +| Date | Phase | Decision | Rationale | +|---|---|---|---| + +## Next Actions +- [ ] action (owner, due) +``` + +## docs/MARKETING.md (created by Phase 1) + +```markdown +# Marketing + +## Target Market & Avatar +PVP niche choice · one-paragraph avatar. + +## Before / During / After Grid +| Phase | Square | Current state | Plan | +|---|---|---|---| + +## Channels +| Channel | Approach | Owner | Status | +|---|---|---|---| + +## Word-of-Mouth (STEPPS) +| Lever | Idea | Status | +|---|---|---| + +## Outbound Process +Roles, sequences, qualification, handoff. + +## Referral & Invite Mechanics + +## Nurture Sequences +``` diff --git a/.agents/skills/grow-website/SKILL.md b/.agents/skills/grow-website/SKILL.md new file mode 100644 index 00000000..0c67b300 --- /dev/null +++ b/.agents/skills/grow-website/SKILL.md @@ -0,0 +1,241 @@ +--- +name: grow-website +description: 'Guided journey from a website with traffic it under-converts to a research-driven growth engine that captures more leads, persuades more buyers, sells a sharper offer, and earns referrals. Orchestrates eight skills phase by phase - cro-methodology, scorecard-marketing, storybrand-messaging, made-to-stick, influence-psychology, hundred-million-offers, contagious, one-page-marketing - asking the user questions at every decision point and recording results in the project docs/ folder (WEBSITE.md, OFFER.md, MARKETING.md, GROW-WEBSITE-PLAN.md) so the journey resumes across sessions. Use when the user wants to raise conversion on a site that already has traffic, capture more leads, sharpen a weak offer, add referral loops, or says ''my site gets visitors but nobody buys''. If a broken funnel or usability friction is the real blocker, run improve-website first; if there is no site yet, use create-website. For one framework in isolation, invoke that skill directly.' +license: MIT +metadata: + author: wondelai + version: "1.0.0" +--- + +# Grow a Website + +Take a site that already has traffic and under-monetizes it, and turn it into a research-driven growth engine: more leads captured, more buyers persuaded, a sharper offer, and visitors who bring more visitors. This journey runs eight phases — the agent asks before it decides at every fork, and all state lives in `docs/` so you can stop and resume across sessions. It sequences the work; it does not redesign the site on a hunch. + +## Core Principle + +**Most traffic problems are conversion problems in costume: capture and convert the visitors you have before buying more.** This skill sequences the phases, asks the decision questions, and records every choice in `docs/`. The constituent skills carry the method — invoke them rather than improvising their frameworks. Research comes before optimization, and the offer comes before the page polish, always. + +## Journey Map + +| Phase | Skill | Question it answers | Artifact | +|---|---|---|---| +| 1. Discover why visitors leave | cro-methodology | Why do visitors not convert, and what is worth testing? | Extends docs/WEBSITE.md, docs/METRICS.md, docs/EXPERIMENTS.md | +| 2. Capture the not-ready 97% | scorecard-marketing | How do we keep the leads who aren't ready to buy? | Extends docs/WEBSITE.md, docs/MARKETING.md | +| 3. Clarify the message | storybrand-messaging | Can a stranger tell what we do in five seconds? | Extends docs/POSITIONING.md | +| 4. Make the message stick | made-to-stick | Will they remember it when they are ready to buy? | Extends docs/POSITIONING.md, docs/WEBSITE.md | +| 5. Add proof and triggers | influence-psychology | Why should they believe us, and act now? | Extends docs/WEBSITE.md | +| 6. Rebuild the offer | hundred-million-offers | Is the thing we sell irresistible? | Extends docs/OFFER.md, docs/EXPERIMENTS.md | +| 7. Engineer shareability | contagious | Will visitors bring us more visitors? | Extends docs/MARKETING.md, docs/WEBSITE.md | +| 8. Connect the lifecycle | one-page-marketing | Do the wins link into one compounding engine? | Extends docs/MARKETING.md, docs/METRICS.md | + +## Operating Rules + +1. **Resume first.** Before anything else, read `docs/GROW-WEBSITE-PLAN.md` and every artifact in the Journey Map. If the tracker exists, summarize the journey state in 3-5 lines and ask which phase to enter. Done when the user has confirmed an entry point. A journey with a tracker is resumed, never restarted. +2. **Intake on first run only.** No tracker: run the Intake below, then create `docs/GROW-WEBSITE-PLAN.md` with every phase statused `pending | in-progress | awaiting-evidence | done | deferred: reason | skipped: reason`. Done when the tracker exists and the user has confirmed the phase plan. +3. **Phase entry.** Announce: what the phase does, the decision it forces, the artifact it produces, rough effort. Offer proceed / skip / defer — phases marked GATE may be deferred, never skipped. Mark the phase `in-progress` on proceed. Done when the user chose. +4. **Skill invocation and fallback.** Invoke the phase's skill by its slug. If it is not available, offer: `npx skills add wondelai/skills/ --global`. If the user declines, run the phase from its Brief — the minimum viable method. State which mode you are in. +5. **In-phase decisions.** Ask every question under "Decide with the user" — with concrete options and your recommendation. Record the choice in the tracker's Key Decisions. A decision made silently is a defect. +6. **Phase exit.** Present the draft artifact content for sign-off before writing. On approval: write or extend the docs/ files, update the tracker (status, Key Decisions, Next Actions). Done when the files are written and the phase row shows `done`. +7. **Artifact discipline.** Read before writing; create a file only if missing, otherwise extend — add or update your sections, preserve everyone else's. Files are UPPERCASE in `docs/`. Every recommendation lands as a checkbox or a table row with owner and priority. See [references/artifact-templates.md](references/artifact-templates.md) when creating a docs/ file for the first time — create it from the full skeleton (all section headings), then fill the sections your phase names. +8. **Every scarcity claim, testimonial, and share incentive must be true.** When a persuasion tactic needs inventing evidence, replace it with a tactic that uses evidence you have. A countdown that resets, a "only 2 left" that never changes, or a fabricated review poisons every honest claim that follows it. + +## Intake + +Ask these before creating the tracker: + +1. What is the site, and what is its primary conversion action — signup, purchase, booking, lead form? (Anchors every phase and defines where the funnel ends.) +2. What traffic and conversion numbers do you have — sessions, bounce rate, conversion rate, worst-performing high-traffic page? (Gates Phase 1's funnel map and whether A/B testing can reach significance.) +3. What visitor research already exists — exit surveys, support tickets, chat logs, reviews? (Raw material for the O/CO table; if none, Phase 1 starts by gathering it.) +4. Do you already capture leads (list, lead magnet), and how well does it convert? (Gates Phase 2.) +5. What are you selling, at what price, and do visitors call it "too expensive"? (Gates Phase 6's offer rebuild.) +6. Is there existing positioning or messaging — a POSITIONING.md, a brand script, a one-liner? (Gates Phases 3-4; reuse rather than redo.) +7. What is your monthly traffic volume? (Decides Phase 1's testing approach: enough for bold A/B tests to reach significance, or lean on qualitative research and reason from principles.) + +Skip heuristics: skip Phase 2 when a lead-capture funnel already converts well; skip Phases 3-4 when a stranger already passes the five-second test on the message; skip Phase 6 when the offer converts and price is not an objection; skip Phase 7 when there is no naturally shareable asset and referral is not a realistic channel. + +Then create `docs/GROW-WEBSITE-PLAN.md` from the template and confirm the plan. Done when `docs/GROW-WEBSITE-PLAN.md` exists with every phase statused and the user has confirmed the plan. + +## Phases + +### Phase 1 — Discover why visitors do not convert (cro-methodology) + +**Purpose:** Replace guesses about why visitors leave with evidence, and turn it into a ranked test queue. + +**Brief (fallback):** Don't guess, discover. Map the funnel to find blocked arteries (high-traffic +pages that drop off) and missing links. Research visitors on three axes: who they are, what blocks +them (UX), what stops them (objections). Build an Objection / Counter-Objection table in the visitor's +own words, place each counter at its point of friction, and inventory proof you have but do not show. +Queue bold experiments — not button colors — scored by ICE. + +**Invoke:** `cro-methodology` with the primary conversion action, traffic numbers, and any research (exit surveys, support tickets, chat logs, reviews) from intake. Ask for a funnel map, an O/CO table sourced from real visitor language, an audit of the worst high-traffic page scored 0-10, and 3-5 ICE-scored experiment ideas with a hypothesis for the top two. + +**Decide with the user:** (1) Which page is the blocked artery to attack first — highest traffic times worst conversion? (2) Is there enough research to source objections, or do we run exit surveys first (status awaiting-evidence)? (3) Which two experiments enter the queue — recommend the highest ICE that could plausibly double conversion, not a meek tweak. + +**Artifact:** Extend docs/WEBSITE.md `## Audit Findings` and `## Conversion Elements` (the O/CO table with placement); docs/METRICS.md `## Funnel` (stages, drop-off, benchmark, bottleneck); docs/EXPERIMENTS.md `## Experiment Backlog` (ICE) and `## Experiment Cards` for the top two. Update the tracker. + +**Done when:** the funnel is mapped with the blocked artery named, WEBSITE.md holds an O/CO table with counters placed at their friction point, and two ICE-scored experiment cards exist with pre-committed primary, secondary, and guardrail metrics. + +### Phase 2 — Capture the 97% who are not ready to buy (scorecard-marketing) + +**Purpose:** Keep the visitors who will not buy today with an interactive assessment instead of losing them at exit. + +**Brief (fallback):** About 3% of a market is ready now; capture the rest. A scorecard or quiz +converts 30-50% versus 3-10% for a PDF. Four steps: a landing page built on the 3 Cs (Clarity, +Credibility, Connection); a questionnaire that captures the email before the questions, then 8-15 +scored questions in 2-7 categories; a results page with dynamic content per tier that creates +tension between where the visitor is and could be; a follow-up engine segmented by score. + +**Invoke:** `scorecard-marketing` with the audience and the primary conversion action. Ask for the concept hook (pressure-test several), the scored questions and their categories, the tiered results copy, the pre-question capture form, and tier-segmented follow-up emails. + +**Decide with the user:** (1) The concept hook — pick a "moving toward" framing that taps the strongest dormant desire over a fear-based one. (2) How many tiers and where the score cutoffs sit. (3) Does an adequate capture funnel already exist, in which case skip? + +**Artifact:** Extend docs/WEBSITE.md `## Lead Capture` (scorecard funnel design: hook, questions, tiers, capture-first form); docs/MARKETING.md `## Nurture Sequences` (the tier-segmented follow-up tracks). Update the tracker. + +**Done when:** WEBSITE.md documents a scorecard that captures email before question one with dynamic results by tier, and MARKETING.md holds a separate follow-up track for each tier. + +### Phase 3 — Make the message clear before clever (storybrand-messaging) + +**Purpose:** Ensure a stranger can tell what you do, for whom, and why to care within five seconds. + +**Brief (fallback):** Make the customer the hero and the brand the guide — Yoda, not Luke. Run SB7: a +Character who wants one thing; a Problem named at three levels (external, internal, philosophical — +sell to the internal); a Guide with empathy and authority; a 3-4 step Plan; a direct and repeated +Call to Action; the stakes of Failure; a picture of Success. Produce a one-liner: "We help [character] +who struggle with [problem] to [solution] so they can [result]." Clear beats clever. + +**Invoke:** `storybrand-messaging` with the objections and proof inventory from Phase 1 — they are the raw material for the Problem and the Guide's authority — plus any existing positioning. Ask for a full brand script, a homepage hero rewrite, and 2-3 one-liner options. + +**Decide with the user:** (1) Which internal problem to lead with. (2) Which one-liner a stranger could repeat after hearing it once. (3) The direct plus transitional CTA wording. + +**Artifact:** Extend docs/POSITIONING.md `## Brand Script (StoryBrand)`, `## One-Liner`, and `## Key Messages` (surface | message | status). Update the tracker. + +**Done when:** POSITIONING.md holds a completed brand script, a chosen one-liner, and key messages mapped to surfaces — and the hero passes the five-second test. + +### Phase 4 — Make the message stick in memory (made-to-stick) + +**Purpose:** Make the clear message memorable so a visitor who is not ready yet still recalls you when they are. + +**Brief (fallback):** Apply SUCCESs: Simple, Unexpected, Concrete, Credible, Emotional, Stories. Beat +the Curse of Knowledge — replace jargon and abstraction with concrete, human-scale specifics ("orders +arrive in 30 minutes, still hot"; "saves 16 hours a month"). Lead with the counterintuitive thing, +not the expected one. Wrap the transformation in one specific customer's story: if I look at the one, +I will act. + +**Invoke:** `made-to-stick` with the Key Messages and page copy from Phase 3. Ask for a Curse-of-Knowledge audit flagging every abstract claim, concrete rewrites with real numbers, and one flagship case study turned into a sticky story. + +**Decide with the user:** (1) Which claims to make concrete first — the highest-traffic pages. (2) Which case study becomes the flagship story. + +**Artifact:** Extend docs/POSITIONING.md `## Key Messages` with a `### Sticky Rewrites` subsection (concrete, de-jargoned versions), and docs/WEBSITE.md `## Page Briefs` copy blocks. Update the tracker. + +**Done when:** every abstract claim on the priority pages has a concrete rewrite recorded, and one sticky customer story exists. + +### Phase 5 — Add the proof and triggers that move people to yes (influence-psychology) + +**Purpose:** Answer "why should I believe you?" and "why act now?" with placed, ethical persuasion. + +**Brief (fallback):** Seven principles: Reciprocity, Commitment and Consistency, Social Proof, +Authority, Liking, Scarcity, Unity. For an existing site, social proof and authority usually carry +the most weight. Specific numbers beat vague claims ("2,347 founders" over "thousands"); similar-other +proof beats celebrity proof; admitting a small weakness before your strengths raises trust. Stack +several principles on the highest-value pages. Real numbers, real deadlines, real scarcity only. + +**Invoke:** `influence-psychology` with the O/CO table and proof inventory from Phase 1. Ask for a principle-by-principle audit, a redesigned trust-signal section that stacks social proof plus authority plus genuine scarcity, and a micro-commitment rewrite of the signup flow — flagging anything that crosses into manipulation. + +**Decide with the user:** (1) Which principles to prioritize by the objections research surfaced. (2) Which proof is real and displayable now versus which must be gathered. (3) Remove any fake scarcity currently on the site — confirm. + +**Artifact:** Extend docs/WEBSITE.md `## Conversion Elements` (add proof and trigger rows with placement and status). Update the tracker. + +**Done when:** WEBSITE.md's conversion elements stack real social proof, authority, and genuine scarcity at their point of friction, and no fake scarcity remains on the site. + +### Phase 6 — Rebuild the thing you are actually selling (hundred-million-offers) + +**Purpose:** Make the underlying offer irresistible before optimizing the page around it — the most upstream lever in the stack. + +**Brief (fallback):** A Grand Slam Offer sells despite mediocre marketing. Value = (Dream Outcome +times Perceived Likelihood) divided by (Time Delay times Effort and Sacrifice) — raise the top, cut +the bottom. List every obstacle to the dream outcome and solve each; Trim and Stack (cut +low-value/high-cost, stack high-value/low-cost); add named bonuses that each kill an objection; attach +a risk-reversing guarantee; add ethical scarcity; name it with MAGIC. A strong guarantee reduces +refunds; raising price can raise conversion. + +**Invoke:** `hundred-million-offers` with the current offer and price, and whether visitors call it "too expensive." Ask for a Value-Equation score, an obstacle list with a solution for each, named bonuses, a guarantee, and MAGIC name options. + +**Decide with the user:** (1) Is "too expensive" a price problem or a value-perception problem? (2) Which bonuses and which guarantee to commit to. (3) Price and tier structure. (4) Queue the new offer as a bold experiment — a new offer is exactly what CRO says is worth testing. + +**Artifact:** Extend docs/OFFER.md `## Offer Stack`, `## Tiers (Good / Better / Best)`, and `## Price Metric`; add a card to docs/EXPERIMENTS.md `## Experiment Cards` to test the new offer. Update the tracker. + +**Done when:** OFFER.md holds a Grand Slam Offer (value equation, named bonuses, real guarantee, MAGIC name) and it is queued as an experiment card with pre-committed metrics. + +### Phase 7 — Make visitors bring you more visitors (contagious) + +**Purpose:** Turn each satisfied visitor into a source of new ones by design, not by luck. + +**Brief (fallback):** Virality is engineered. STEPPS: Social Currency, Triggers, Emotion, Public, +Practical Value, Stories. A personalized scorecard result is high Social Currency — a remarkable stat +about themselves. Practical Value (a calculator, a genuinely useful resource) gets forwarded; frame +promotions with the Rule of 100. Public ("Powered by [you]", behavioral residue) markets after use. +Stories must pass the Trojan Horse test. Only ~7% of word-of-mouth is online — design things worth +talking about, not just share buttons. + +**Invoke:** `contagious` with the scorecard results page from Phase 2 and the site's highest-value asset. Ask for a STEPPS audit scored out of 10, a shareable redesign of the results page with a share card that passes the Trojan Horse test, and Public / behavioral-residue features. + +**Decide with the user:** (1) Which asset is the shareable one. (2) Which two or three STEPPS drivers to engineer in. (3) The share incentive — must be a real benefit, never a fabricated reward. + +**Artifact:** Extend docs/MARKETING.md `## Word-of-Mouth (STEPPS)` and `## Referral & Invite Mechanics`; extend docs/WEBSITE.md `## Lead Capture` with the shareable results-page design. Update the tracker. + +**Done when:** MARKETING.md's STEPPS table names the two-to-three drivers engineered in against a specific shareable asset, and the referral mechanics are documented. + +### Phase 8 — Tie the lifecycle together so wins compound (one-page-marketing) + +**Purpose:** Connect acquisition, nurture, conversion, and referral into one engine so wins do not leak out the back. + +**Brief (fallback):** Marketing is a process, not an event. The 3x3 grid: BEFORE (Target Market, +Message, Media), DURING (Capture Leads, Nurture, Convert), AFTER (Experience, Lifetime Value, +Referrals). The AFTER column is usually where the money hides — retention costs 5-25x less than +acquisition, and a 5% retention gain lifts profit 25-95%. The number-one reason customers do not +refer is that nobody asked. + +**Invoke:** `one-page-marketing` as an audit tying Phases 1-7 together — the scorecard fills Capture, the offer fills Convert, Contagious powers Referrals. Ask for the 9-square plan scored 0-10 per square, flagging empty AFTER squares, and a lead-nurture sequence at a 3-to-1 value-to-ask ratio. + +**Decide with the user:** (1) Which empty squares to fill first — usually Experience, Lifetime Value, Referrals. (2) The ascension model for best customers. (3) Retention and LTV targets to track. + +**Artifact:** Extend docs/MARKETING.md `## Target Market & Avatar`, `## Before / During / After Grid`, `## Referral & Invite Mechanics`, and `## Nurture Sequences`; extend docs/METRICS.md `## Baselines & Targets` (retention, LTV). Update the tracker. + +**Done when:** MARKETING.md's Before / During / After grid has no empty AFTER squares, and retention and LTV targets are recorded in METRICS.md. + +## Optional Phases + +| Skill | Add when | Artifact | +|---|---|---| +| lean-analytics | growth work has no single metric keeping it honest | Extends docs/METRICS.md | +| high-perf-browser | slow pages bleed the traffic you already earn | Extends docs/WEBSITE.md | +| hooked-ux | return visits should become a habit loop | Extends docs/PRODUCT.md | +| ux-heuristics | friction, not persuasion, blocks the funnel | Extends docs/WEBSITE.md | + +Optional phases follow the same operating rules; insert where the Add-when condition first becomes true. + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Optimizing before researching | Run cro-methodology's visitor research first; change only what the evidence flags, not what a meeting brainstormed. | +| Testing meek tweaks (button colors) | Queue bold changes — a new offer, value prop, or full-page rewrite — ICE-score them, and run each to significance over a full business cycle. | +| Capturing email after the quiz | Fire the lead form before question one (scorecard-marketing) so an abandoned assessment still leaves you a lead to recover. | +| Faking scarcity or proof | Use only true numbers, deadlines, and testimonials; one fake claim (influence-psychology / hundred-million-offers) poisons every honest one after it. | +| Polishing the page while ignoring the offer | Rebuild the offer upstream with hundred-million-offers before more page tests; "too expensive" is usually a value-perception problem. | +| Ignoring the AFTER phase | Fill the empty Experience / Lifetime Value / Referrals squares with one-page-marketing — retention and referral are the cheapest growth there is. | + +## Completing the Journey + +Exit checklist: + +- [ ] WEBSITE.md has an O/CO table with each counter placed at its point of friction, and audit findings resolved or queued. +- [ ] A scorecard captures email before the questions, with tier-segmented follow-up recorded in MARKETING.md. +- [ ] OFFER.md holds a Grand Slam Offer (value equation, named bonuses, real guarantee) queued as a bold experiment in EXPERIMENTS.md. +- [ ] MARKETING.md's Before / During / After grid has no empty AFTER squares (Experience, Lifetime Value, Referrals). +- [ ] At least one bold experiment is running to significance with pre-committed metrics. + +Close the tracker: every phase `done` or `skipped: reason`, and any open Next Actions carried into the artifacts they belong to. Then route forward: + +- When the growth loops belong inside the product, continue with `grow-app`. +- When the site is beyond saving and a rebuild is cheaper, continue with `create-website`. diff --git a/.agents/skills/grow-website/references/artifact-templates.md b/.agents/skills/grow-website/references/artifact-templates.md new file mode 100644 index 00000000..9fe1f87b --- /dev/null +++ b/.agents/skills/grow-website/references/artifact-templates.md @@ -0,0 +1,105 @@ +# Artifact Templates — grow-website + +Skeletons this metaskill creates in the user's docs/ folder. Extend-only artifacts are governed by the section headings named in each phase; the three below (MARKETING.md, WEBSITE.md, EXPERIMENTS.md) are the ones grow-website most often authors from scratch, so their full skeletons are copied here. Read before writing, create only if missing, and preserve any sections another journey already wrote. + +## Tracker: docs/GROW-WEBSITE-PLAN.md + +```markdown +# Grow a Website Plan + +## Context +Intake answers, date started, project specifics. + +## Phase Status +| Phase | Skill | Status | Artifact | Date | +|---|---|---|---|---| +| 1. Discover why visitors leave | cro-methodology | pending | WEBSITE.md, METRICS.md, EXPERIMENTS.md | | +| 2. Capture the not-ready 97% | scorecard-marketing | pending | WEBSITE.md, MARKETING.md | | +| 3. Clarify the message | storybrand-messaging | pending | POSITIONING.md | | +| 4. Make the message stick | made-to-stick | pending | POSITIONING.md, WEBSITE.md | | +| 5. Add proof and triggers | influence-psychology | pending | WEBSITE.md | | +| 6. Rebuild the offer | hundred-million-offers | pending | OFFER.md, EXPERIMENTS.md | | +| 7. Engineer shareability | contagious | pending | MARKETING.md, WEBSITE.md | | +| 8. Connect the lifecycle | one-page-marketing | pending | MARKETING.md, METRICS.md | | +Statuses: pending · in-progress · awaiting-evidence · done · deferred: · skipped: + +## Key Decisions +| Date | Phase | Decision | Rationale | +|---|---|---|---| + +## Next Actions +- [ ] action (owner, due) +``` + +## docs/WEBSITE.md + +```markdown +# Website + +## Sitemap + +## Page Briefs +### / (home) +- Purpose & primary conversion action: +- Message (from POSITIONING.md): +- CTA (direct + transitional): +- Copy blocks: + +## Conversion Elements +| Objection (Big 5) | Counter | Placement | Status | +|---|---|---|---| + +## Audit Findings +| Issue | Severity (0-4) | Fix | Status | +|---|---|---|---| + +## Lead Capture +Scorecard/quiz funnel design. +``` + +## docs/EXPERIMENTS.md + +```markdown +# Experiments + +## Experiment Cards +### EXP-001 — [name] +- Hypothesis: We believe [outcome] if [who] [does what] because [reason] +- Type: sprint / smoke test / concierge / painted door / A-B +- Primary metric & threshold (pre-committed): +- Guardrail metric: +- Decision rule (pivot / persevere / iterate): +- Result & verdict: + +## Experiment Backlog +| Idea | ICE (impact/confidence/ease) | Status | +|---|---|---| +``` + +## docs/MARKETING.md + +```markdown +# Marketing + +## Target Market & Avatar +PVP niche choice · one-paragraph avatar. + +## Before / During / After Grid +| Phase | Square | Current state | Plan | +|---|---|---|---| + +## Channels +| Channel | Approach | Owner | Status | +|---|---|---|---| + +## Word-of-Mouth (STEPPS) +| Lever | Idea | Status | +|---|---|---| + +## Outbound Process +Roles, sequences, qualification, handoff. + +## Referral & Invite Mechanics + +## Nurture Sequences +``` diff --git a/.agents/skills/high-output-management/SKILL.md b/.agents/skills/high-output-management/SKILL.md new file mode 100644 index 00000000..30976da3 --- /dev/null +++ b/.agents/skills/high-output-management/SKILL.md @@ -0,0 +1,212 @@ +--- +name: high-output-management +description: 'Manage for output using Grove''s "High Output Management": a manager''s output is their organization''s output, raised by high-leverage activities. Use when the user mentions "high output management", "managerial leverage", "one-on-ones", "1:1 agenda", "OKRs", "performance review", "task-relevant maturity", "delegation", "meeting overload", "new manager", "how do I run a 1:1", or "just got promoted to manager". Also trigger when structuring a manager''s calendar and meeting cadence, designing team metrics, running planning, coaching delegation, or preparing performance reviews. Covers leverage, production principles, meetings as the medium of management, decisions, OKRs, and task-relevant maturity. For intrinsic motivation, see drive-motivation. For a company operating system, see traction-eos.' +license: MIT +metadata: + author: wondelai + version: "1.2.0" +--- + +# High Output Management + +Manage teams the way Andy Grove ran Intel: a manager's output is not what the manager does — it is what their organization produces. This skill turns *High Output Management* into auditable practice: production principles for knowledge work, output indicators, managerial leverage, meetings as the medium of management, clean decisions, OKRs, and a management style matched to task-relevant maturity. + +## Core Principle + +**A manager's output = the output of their organization + the output of the neighboring organizations under their influence.** Nothing a manager does — emails, meetings, reviews, decisions — counts in itself; it counts only through how it raises that combined output. Since managerial time is the scarce input, the craft reduces to one question asked relentlessly: of everything I could do right now, what creates the most output per hour spent? Choose high-leverage activities; eliminate negative-leverage ones. + +## Scoring + +**Goal: 10/10.** Rate management practices, calendars, and processes 0-10 against the principles below. State the current score and the specific changes needed to reach 10/10. + +- **9-10:** Output indicators with quality pairs, subordinate-owned 1:1s on a TRM-based cadence, delegation with task-level monitoring, OKRs that stretch without driving pay, calendar built around forecasted key events +- **7-8:** Process meetings run well, but a few activity metrics, ad hoc decision meetings, or skipped training sessions remain +- **5-6:** 1:1s happen irregularly, indicators track busyness, delegation is all-or-nothing, planning produces documents instead of actions +- **3-4:** Management by interruption: status theater, decisions made by rank, reviews as annual surprises +- **0-2:** No 1:1s, no indicators, firefighting as the operating mode, output invisible and unmeasured + +## Framework + +### 1. Production Principles for Knowledge Work + +**Core concept:** Grove's breakfast factory — deliver a three-minute egg, buttered toast, and hot coffee simultaneously, at acceptable quality and lowest cost — contains all of production: build the flow around the limiting step (the egg), fix problems at the lowest-value stage, batch where setup costs dominate, and choose deliberately between building to forecast and building to order. Every team — engineering, support, recruiting — runs a production line, whether or not anyone has drawn it. + +**Why it works:** Knowledge work hides its assembly line, and invisible flow invites firefighting. Production thinking makes flow visible: once you know the limiting step, everything else gets scheduled around it; once defects are caught at the egg stage instead of on the customer's plate, fixing them costs a fraction. + +**Key insights:** +- Build around the limiting step: find the longest, hardest, or most expensive stage and offset everything else from it — often code review, staging access, or one overloaded specialist +- Fix problems at the lowest-value stage: kill a flawed spec in review, not after three sprints of building on it +- Batch work with high setup cost — interviews, code reviews, interrupt handling — so the setup amortizes across the batch +- Most knowledge work is built to forecast, not to order: staff the pipeline to the forecast and accept controlled risk, as the toast goes down before the customer orders +- You cannot watch all the work: treat it as a black box and cut windows into it with a handful of indicators + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Sprint flow | Schedule around the limiting step | Review is the bottleneck → protect reviewer hours before starting new work | +| Quality gates | Inspect at the lowest-value stage | Spec review kills a flawed design before a three-week build | +| Hiring pipeline | Batch and build to forecast | Phone screens batched Tue/Thu; interviewer capacity staffed to the offer-date forecast | + +**Ethical boundary:** Run systems hot, not humans — production thinking optimizes the work, never treats people as interchangeable machines. + +See: [references/indicators-and-production.md](references/indicators-and-production.md) when finding a limiting step or building a dashboard — limiting-step analysis, worked indicator pairs, leading vs trend indicators, stagger charts, and how to run an operation review. + +### 2. Indicators That Don't Lie + +**Core concept:** Measure output, not activity — what the team shipped that survived, not how busy it looked. Pair every quantity indicator with a quality counterpart so neither can be optimized at the other's expense, favor leading indicators that buy time to act, and report forecasts in stagger charts that show how each forecast evolved. + +**Why it works:** People do what management measures, so an unpaired indicator is an instruction to game it. The pair closes the loop: push throughput and the escape rate exposes the corner-cutting. Leading indicators and stagger charts convert measurement from autopsy to steering. + +**Key insights:** +- Lines of code, hours logged, and tickets touched are activity; features alive in production and problems solved are output +- Pair quantity with quality: deploys/week with change-failure rate, ticket closes with reopens, velocity with incident count +- Leading indicators (review queue age, build flakiness, on-call page rate) warn before output drops; trend indicators compare output against your own history and forecast +- A stagger chart re-forecasts the same horizon every period; reading down a column shows whether forecasting is honest, optimistic, or sandbagged +- Administrative work measures like a factory: offers per recruiter-week, invoices processed per day — always with a quality pair + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Eng dashboard | Pair quantity with quality | Deploys/week paired with change-failure rate | +| Support ops | Output plus its quality shadow | Tickets resolved/day paired with reopen rate and CSAT | +| Quarterly forecast | Stagger chart | Re-forecast quarter-end ARR monthly; drift visible down each column | + +**Ethical boundary:** Indicators measure the work, not the worker — used for surveillance, they teach people to optimize the number instead of the output. + +### 3. Managerial Leverage + +**Core concept:** Leverage is the output created per unit of managerial time. High-leverage activities affect many people at once (training, well-prepared decisions, information gathering) or redirect months of work with a small, well-timed nudge. The calendar is the manager's production system: forecast the key events, batch the rest, and say no at the source when capacity is full. + +**Why it works:** Managerial activities differ by orders of magnitude in output per hour — ninety minutes preparing a review shapes a year of someone's work, while a day of meddling subtracts output. A manager who lets the calendar happen to them spends prime hours on whatever shouted loudest. + +**Key insights:** +- Negative leverage is real: meddling (supervising an expert in detail), waffling (stalling a decision others wait on), and a manager's visible gloom all multiply downward through the team +- Delegate the tasks you know best — monitoring them costs you least — and remember that delegation without monitoring is abdication +- Monitor at the task level, not the person level: sample like incoming inspection, deeper at low task-relevant maturity, lighter as it rises +- Forecast your limiting steps: put 1:1s, staff meetings, reviews, and planning on the calendar first and let interrupts fill around them, not the reverse +- Run below 100% load: a fully booked manager turns every surprise into a delay for everyone downstream; saying no early is cheaper than failing late +- Batch interruptions with office hours and known checkpoints instead of letting them shred maker time + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Week design | Forecast fixed events, batch the rest | 1:1s Tue-Wed mornings, PR reviews batched daily at 4pm, Monday deep-work block | +| Delegation | Monitoring depth by TRM | New hire's first migration: plan review plus daily spot checks; veteran's: rollout plan only | +| Interrupts | Convert random pings to office hours | Two daily drop-in slots replace ad hoc Slack escalations | + +**Ethical boundary:** Leverage means multiplying others' output, never hoarding information or approvals until you become the bottleneck everyone must visit. + +See: [references/leverage-and-calendar.md](references/leverage-and-calendar.md) when auditing a calendar or setting up delegation — the weekly leverage audit, positive/negative-leverage catalog, delegation protocol with TRM-based monitoring depth, calendar-redesign procedure, and interruption management. + +### 4. Meetings Are the Medium of Management + +**Core concept:** A meeting is not a symptom of bad management; it is where managerial work — gathering information, imparting it, deciding, nudging — actually happens. Process-oriented meetings (one-on-ones, staff meetings, operation reviews) run on a regular cadence and should carry the bulk of that work, roughly a quarter of the calendar. Mission-oriented meetings are ad hoc and exist solely to produce a decision. + +**Why it works:** Regularity makes meetings cheap — standing agendas, shared expectations, zero setup cost — and starves the expensive kind: issues get caught small in 1:1s and staff meetings instead of exploding into emergency decision meetings. Grove's malorganization test: ad hoc mission-oriented meetings eating more than about a quarter of managerial time means the process is broken. + +**Key insights:** +- The 1:1 is the subordinate's meeting: they own the agenda and bring it; the supervisor's job is to listen and learn what is really going on +- Set 1:1 frequency by task-relevant maturity, not seniority or affection: new-to-task weekly, veterans every few weeks — never less than monthly +- Both sides keep a "hold" list of non-urgent items for the next 1:1 — it batches interruptions away +- The supervisor takes the notes: writing down agreed actions signals commitment and forces follow-up +- "One more thing": after the agenda is done, ask what else is on their mind — the real issue often surfaces in the last five minutes +- Staff meetings are controlled free discussion — the manager moderates as a Socratic prodder, not a lecturer; a recurring "ad hoc" meeting is a process meeting in denial + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| New report | Weekly 1:1, their agenda | First 90 days: 60 minutes weekly; agenda arrives the day before | +| Team sync | Controlled free discussion | Two-minute updates, then debate on two pre-flagged issues | +| Recurring "urgent" meeting | Convert to process | Third ad hoc incident review this month becomes a standing ops review | + +**Ethical boundary:** Hijacking the 1:1 for status extraction teaches people to stop bringing real problems — status belongs in writing. + +See: [references/meetings-and-one-on-ones.md](references/meetings-and-one-on-ones.md) when designing a meeting cadence or running a 1:1 — the full 1:1 playbook with agenda templates, staff-meeting design, operation-review roles, and meeting-cost math for when to kill a meeting. + +### 5. Decisions and Planning (incl. OKRs) + +**Core concept:** The ideal decision moves through free discussion (all views aired, dissent welcome), a clear decision (stated crisply — the more contentious, the crisper), and full support (disagree and commit). Decisions belong at the lowest competent level, closest to current technical knowledge. Planning runs the same arc: assess environmental demand, face present status honestly, close the gap — because the output of planning is decisions and actions taken now, not documents. + +**Why it works:** Free discussion surfaces knowledge that lives at the edges; a clear decision prevents the costliest outcome, ambiguity; full support lets the organization move without unanimity. And today's firefight is yesterday's planning failure — planning works on next year's gap, not this week's smoke. + +**Key insights:** +- Peer-group syndrome — peers circling, waiting for someone senior to lean — is broken by peer-plus-one: one senior person in the room sanctioned to tip the decision +- Before any decision meeting, answer six questions: what decision, by when, who decides, who is consulted, who ratifies or vetoes, who is informed +- When no one person has both, pair the freshest technical knowledge with the strongest organizational judgment +- Reversing a decision quietly is waffling; reversing it openly on new facts is management +- MBO/OKRs answer two questions: where do I want to go (objective), and how will I pace myself to see I am getting there (key results) +- Keep objectives few and key results measurable enough to score without argument; cascade so one level's key results become the next level's objectives — and never wire them mechanically to compensation + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Architecture choice | Free discussion → clear decision → commit | RFC debated one week; tech lead decides; dissent recorded, then full support | +| Decision prep | Six-question brief | "Pick payments vendor by Jun 30; platform PM decides; eng and finance consulted; VP ratifies" | +| Quarterly planning | Cascading OKRs | Company KR "checkout p95 under 800ms" becomes the platform team's objective | + +See: [references/decisions-planning-okrs.md](references/decisions-planning-okrs.md) when prepping a contentious decision or a planning cycle — the six-question brief, peer-group-syndrome counters, three-step planning, and a Grove-style OKR cascade with pitfalls. + +### 6. Task-Relevant Maturity, Reviews, and Training + +**Core concept:** There is no universally good management style. The right style depends on the subordinate's task-relevant maturity (TRM) — their experience, training, and confidence for this specific task: low TRM calls for structured "how" instruction, medium for mutual reasoning about "what and why", high for agreed objectives with light monitoring. TRM is task-specific, not seniority, so style must shift the moment the task does. + +**Why it works:** Mismatched style fails in both directions — hands-off at low TRM is abandonment dressed as empowerment; detailed instruction at high TRM is meddling that destroys ownership. The performance review is where the cost of a mismatch compounds: a year's feedback delivered in the wrong register lands as either neglect or insult. + +**Key insights:** +- A star promoted into management is high-TRM on engineering and low-TRM on managing — structure the new task even for your best person +- The performance review is the single most important form of task-relevant feedback a supervisor gives; its only purpose is improving the recipient's performance +- Assess, don't blend: complete the written assessment first, then separately decide which three messages will actually change next year's output +- No surprises: anything that startles the recipient in a review is the supervisor's failure, logged in public +- The ace who is coasting deserves the most review effort — "keep it up" robs your best performer of their next level +- Once lower needs are met, only an ever-rising, self-set bar motivates (the athlete mindset) — and training is the manager's highest-leverage way to raise that bar: deliver it yourself, because outsourcing training outsources standards + +**Applications:** + +| Context | Application | Example | +|---------|-------------|---------| +| Newly promoted manager | Re-rate TRM per task | Weekly structured 1:1s on hiring and delegation, even for a star engineer | +| Review prep | Assess first, message second | Full written assessment, then the three messages that change next year | +| Team capability | Manager-taught training | EM personally teaches a four-session incident-response course | + +See: [references/case-studies.md](references/case-studies.md) when preparing a review or coaching a newly promoted manager — three worked scenarios (meeting-drowned new manager, velocity-up/quality-down, a botched review repaired with TRM coaching). + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Measuring activity, not output | Busyness is gameable and says nothing about results | Count what shipped and survived; pair quantity with quality | +| Publishing unpaired indicators | The team optimizes the number at quality's expense | Add the quality counterpart before the metric goes live | +| Skipping 1:1s when busy | Cancels the highest-leverage 90 minutes on the calendar | Treat 1:1s as forecasted production steps: reschedule, never drop | +| Decisions by rank | Knowledge lives at the lowest competent level; rank silences it | Free discussion, then a clear decision by the named decider | +| OKRs as a compensation formula | Guarantees sandbagged, safe objectives | Keep OKRs a stretch tool; comp weighs more than OKR hit rate | +| One management style for everyone | Abandons the new, smothers the experienced | Match style to task-relevant maturity, task by task | +| Catching defects at the highest-value stage | Cost multiplies at every stage a flaw survives | Inspect specs and plans, not just production | +| Saving feedback for the annual review | It detonates all at once; trust and the year are both lost | No-surprises rule: deliver feedback when the event happens | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Can you state your team's output in one sentence? | You are managing activity | Define output; build 4-6 indicators around it | +| Does every quantity metric have a quality pair? | The number is being gamed already | Pair it: throughput with escapes, closes with reopens | +| Do you know your team's limiting step? | Flow is built around the wrong constraint | Find where work queues longest; schedule around it | +| Did your reports set the agendas of their last 1:1s? | You ran status meetings instead | Hand the agenda to the subordinate; you take the notes | +| Is 1:1 frequency set by task-relevant maturity? | Someone is over- or under-managed | Weekly for new-to-task, monthly for veterans | +| Was your last big decision made at the lowest competent level? | Rank decided; knowledge watched | Name decider, consulted, and ratifier before the meeting | +| Would your team set the same OKRs if pay weren't attached? | Objectives are sandbagged | Decouple OKRs from the compensation formula | +| Have you personally taught your team anything this quarter? | Highest-leverage activity skipped | Schedule a manager-taught course now | + +## Further Reading + +- [*"High Output Management"*](https://www.amazon.com/High-Output-Management-Andrew-Grove/dp/0679762884?tag=wondelai00-20) by Andrew S. Grove +- [*"Only the Paranoid Survive"*](https://www.amazon.com/Only-Paranoid-Survive-Exploit-Challenge/dp/0385483821?tag=wondelai00-20) by Andrew S. Grove +- [*"Measure What Matters"*](https://www.amazon.com/Measure-What-Matters-Google-Foundation/dp/0525536221?tag=wondelai00-20) by John Doerr + +## About the Author + +**Andrew S. Grove** (1936-2016) fled Hungary at twenty, became Intel's third employee, and rose to president, CEO, and chairman, driving the company's famous pivot from memory chips to microprocessors. Time's 1997 Man of the Year, he mentored a generation of Silicon Valley leaders, and his management-by-objectives system became the OKR method now standard across tech. diff --git a/.agents/skills/high-output-management/references/case-studies.md b/.agents/skills/high-output-management/references/case-studies.md new file mode 100644 index 00000000..83f951a7 --- /dev/null +++ b/.agents/skills/high-output-management/references/case-studies.md @@ -0,0 +1,158 @@ +# Case Studies: High Output Management in Practice + +## Table of Contents + +- [Case Study 1: The Manager Drowning in Meetings](#case-study-1-the-manager-drowning-in-meetings) +- [Case Study 2: Velocity Up, Quality Down](#case-study-2-velocity-up-quality-down) +- [Case Study 3: The Botched Performance Review](#case-study-3-the-botched-performance-review) +- [Key Takeaways](#key-takeaways) + +## Case Study 1: The Manager Drowning in Meetings + +### Context + +Dana, a strong backend engineer at a 120-person fintech, was promoted to engineering manager of a seven-person team. Eight months in, she was working 55-hour weeks: 34 hours of meetings, the rest fragmented into slivers she spent reviewing PRs at night "to stay technical." Her team's delivery had slowed, two engineers were quietly job-hunting, and her own manager labeled the team "a black box." + +### The Problems + +**No process meetings, all ad hoc.** Dana held no regular 1:1s ("no time") and no staff meeting. Information reached her through interruptions — 40+ Slack pings a day — and through emergency meetings that existed because problems were caught late. The absence of process meetings was *creating* the ad hoc ones. + +**Doing instead of managing.** A week log showed 14 hours of IC work: PR reviews she grabbed first, two production fixes she did herself because "it's faster," and a vendor integration she hadn't handed off. Meanwhile, delegation-shaped work — a design doc her senior engineer could own, interview loops, the on-call rotation redesign — sat with her. + +**Negative leverage, invisible.** Three decisions (a schema change, a library upgrade, a hire) had been waiting on her for over two weeks, blocking four people. Her habit of "jumping in to help" on tasks her senior engineers owned was reread by them as distrust. + +### The Intervention + +**Week 1: Log and classify.** Dana logged five days at 30-minute granularity, then classified each block (information gathering / giving, decision-making, nudging, role model, *doing*) and scored leverage. Results: 11% high-leverage, 31% doing, 12% negative leverage (stalled decisions, meddling, unprepared meetings), the rest neutral. The three stalled decisions alone were blocking an estimated 30 engineer-days. + +**Week 2: Install the process meetings.** Weekly 60-minute 1:1s with all seven reports (everyone was effectively new to *her*, and two were new to their tasks), each with a subordinate-owned agenda template and a hold list; one weekly 75-minute staff meeting with a metrics minute, a round, and two debated topics. She cleared the three stalled decisions in the first staff meeting using the six-question brief — two she delegated outright with a named decider. + +**Weeks 2-3: Redesign the calendar as a production system.** Fixed events first (1:1s Tue/Wed mornings, staff meeting Monday after lunch); PR review batched to one 4pm window with a rule that she reviews only designs and risky changes, not routine PRs; two maker blocks; office hours 2-3pm daily replacing always-on Slack; 15% left unscheduled. Standing meetings she merely attended got the cost test — she exited four of them, sending a written update instead. + +**Weeks 3-8: Delegate with TRM-based monitoring.** The vendor integration went to her senior engineer (high TRM: monitoring = rollout plan review only). The on-call redesign went to a mid-level engineer (medium TRM: weekly check on the plan plus spot checks). She wrote down the monitoring plan in each handoff conversation, and announced — publicly — that she would stop reviewing routine PRs. + +### Results After 8 Weeks + +| Metric | Before | After | +|--------|--------|-------| +| Meeting hours/week (Dana) | 34 | 19 (9 process, 10 other) | +| Ad hoc "urgent" meetings/week | 6-8 | 1-2 | +| Slack interruptions/day | 40+ | ~12 (office hours + hold lists) | +| Decisions pending >1 week | 3 | 0 | +| Dana's IC "doing" hours | 14 | 4 (design reviews only) | +| Team features shipped/sprint | 2-3 | 4-5 | +| Hours/week (Dana) | 55 | 44 | + +The two job-hunting engineers stayed; both later said the 1:1s were the reason — problems they had assumed she didn't care about turned out to be hold-list items she now acted on. + +### Lessons Learned + +1. **The absence of process meetings creates the meeting overload.** The ad hoc meetings were the symptom; installing 1:1s and a staff meeting removed their cause. +2. **The log doesn't lie.** Dana guessed she spent "a few hours" on IC work; it was 14. Leverage cannot be improved before it is measured. +3. **Stalled decisions are the most expensive line item.** Twelve percent of her week was negative leverage, and most of its cost landed on other people's calendars. +4. **Delegation needed a published monitoring plan** — once monitoring was announced as task-level QA rather than improvised check-ins, her seniors stopped reading it as distrust. + +## Case Study 2: Velocity Up, Quality Down + +### Context + +A nine-person product team at a B2B SaaS company adopted velocity (story points per sprint) as its headline metric after a slow quarter. Leadership praised rising numbers in all-hands. Two quarters later velocity was up 40% — and the team was miserable: incidents up, on-call brutal, and a key customer threatening to churn over reliability. + +### The Problems + +**A single unpaired indicator.** Velocity was quantity with no quality counterpart. Points rose exactly the way unpaired numbers always rise: tests skipped, migrations deferred, reviews rubber-stamped, stories inflated. Nobody was cheating consciously; the team was doing what management measured. + +**The damage was visible only in unmeasured places.** Change-failure rate had doubled and sev-2 incidents went from two to five per month — but neither was on the dashboard, so velocity reviews stayed celebratory while on-call quietly burned out. + +**The limiting step was being flooded, not fixed.** Code review was the constraint (median 31 hours to first review). Pushing more stories into the sprint didn't raise output; it raised WIP, pressure to rubber-stamp, and escapes. + +**Forecasts had become theater.** Sprint commitments were set to impress and missed by 20-30%, then quietly re-explained. No record of forecast vs actual existed. + +### The Intervention + +**Step 1: Find the limiting step.** The team mapped its flow (spec → build → review → QA → deploy) and measured queue times for the last 30 stories. Review queues dominated: work waited 31 hours median, with WIP piling in front. Responses: reviewer hours protected before new work starts, a WIP limit upstream of review, linters and CI taking mechanical findings off reviewers, and risky-change review batched into a daily window. + +**Step 2: Build the paired dashboard.** Four indicators, shown only together: features shipped per sprint (quantity) with change-failure rate (quality pair); time-to-first-review (quantity) with defect escape rate per 100 merges (quality pair). Two leading indicators alongside: review queue age and on-call pages per week, each with a pre-committed action threshold. + +**Step 3: Stagger-chart the forecasts.** Each sprint, the team re-forecast the next three sprints' completed scope, keeping every prior forecast visible. The first month exposed a systematic 25% over-forecast — discussed openly, without blame, as a bias to correct. + +**Step 4: Monthly operation review.** The lead presented the paired trends to the wider org — reviewing manager briefed to praise honest misses. The first review opened with the lead stating the quality cost of the velocity push before anyone asked. + +### Results After Two Quarters + +| Metric | Peak "velocity era" | After | +|--------|---------------------|-------| +| Story points/sprint | 58 | 49 | +| Change-failure rate | 14% | 5% | +| Sev-2 incidents/month | 5 | 1-2 | +| Median time-to-first-review | 31 h | 7 h | +| Defect escapes per 100 merges | 9 | 3 | +| Sprint forecast error | -25% (over-forecast) | -6% | +| On-call pages/week | 19 | 6 | + +Velocity dropped 15% and nobody minded: features alive and stable in production — the team's actual output — rose, and the churn-threatening customer renewed. + +### Lessons Learned + +1. **Any indicator pushed hard will be achieved; the only question is what is sacrificed.** The pair makes the sacrifice visible before customers report it. +2. **The limiting step, not effort, sets output.** Flooding a constrained flow with more work converts effort into queues and defects. +3. **Stagger charts turn forecast bias into a measured, fixable quantity** — and honesty about forecasts proved contagious into estimates, reviews, and postmortems. +4. **Operation reviews changed incentives upward**: once leadership saw paired trends, "velocity up" stopped being praiseworthy on its own — the metric's audience, not the team, had been the root incentive problem. + +## Case Study 3: The Botched Performance Review + +### Context + +Marcus, a staff engineer and the acknowledged ace of a data platform team, received a "meets expectations minus" annual review from his manager, Lena. He was blindsided — every prior signal had been positive — and furious. He stopped volunteering in design reviews, and his calendar began showing recruiter calls. Lena's own manager asked her to repair it. + +### The Problems + +**Total surprise.** Lena had been dissatisfied for months: Marcus's new charter (leading the streaming-platform migration — coordination, mentoring, stakeholder work) was going badly, while he kept retreating to the batch-pipeline work he was brilliant at. She had said nothing in their sporadic 1:1s. The review was the first time he heard any of it — a supervisor's failure, logged in public. + +**Blended message.** The written review mixed praise and criticism so thoroughly ("exceptional technical depth, though stakeholders sometimes…") that drafting it had felt safe — and reading it felt incoherent. The rating contradicted the prose. Marcus latched onto the praise, concluded the rating was arbitrary, and assigned it to politics. + +**A TRM misread at the root.** Lena had reasoned: staff engineer, ten years' experience, needs no support. But TRM is task-specific. On batch pipelines Marcus's TRM was the highest in the org; on cross-team migration leadership it was *low* — he had never done it. Lena's hands-off style was right for the old task and was abandonment on the new one. He had been coasting on the ace task partly because no one had structured the one he was failing at — the classic ace-who-coasts pattern, mishandled. + +**Comp drove the message.** The "minus" existed mostly to justify a budget-constrained comp outcome, inverting the review's purpose: assessment had been reverse-engineered from money rather than performance. + +### The Repair + +**Step 1: Assess, don't blend — in writing, first.** Lena rewrote the assessment before scheduling any meeting: outcomes only, in two explicitly separated lanes. Batch platform: exceptional, with named results. Migration leadership: not delivering — milestones missed, two partner teams escalating, mentoring not happening — with named instances. Then she chose the three messages that would change next year's output: (1) the migration is now the job and it is going badly; (2) the cause is missing skills for a new kind of task, not effort or talent; (3) here is the structure we'll build, because the goal is for you to lead at the next level. + +**Step 2: Own the failure, then deliver straight.** In the repair conversation Lena opened with her own miss: "You learned this in a review instead of in March. That was my failure, and the no-surprises rule starts now." Then the three messages, undiluted — no praise sandwich. Marcus argued; Lena listened fully (the heart-to-heart a review requires), and did not retract the assessment. + +**Step 3: TRM-matched structure.** Together they re-scoped the work explicitly: migration leadership treated as a low-TRM task — weekly structured 1:1s on it (stakeholder map, milestone plan, a "what/when/how" level of detail that would have insulted him on pipeline work and was relief here), Lena attending his first partner-team negotiations as observer-coach, and a two-session course Lena taught herself on running cross-team programs. Batch-pipeline work stayed high-TRM: objectives and monitoring only. + +**Step 4: No surprises, ever again.** Task-relevant feedback moved to the moment of the event — wins and misses named in the week they happened, logged in the shared 1:1 doc. A six-month interim review was scheduled in writing, with the explicit promise that nothing in it would be new. + +### Results + +| Signal | At the botched review | Six months later | +|--------|----------------------|------------------| +| Migration milestones | 2 of 5 hit | 5 of 5 hit | +| Partner-team escalations | 2 open | 0 | +| Marcus's 1:1 cadence on migration work | Sporadic | Weekly, his agenda | +| Engineers Marcus is mentoring | 0 | 2 | +| Interim review surprises | — | None, by design | +| Retention | Recruiter calls | Took the senior-staff track; stayed | + +The interim review rated the migration work "exceeds" — and contained, verbatim, sentences Marcus had already heard in 1:1s. He later told Lena the original review was the most useful bad day of his career, "but only because of what came after it." + +### Lessons Learned + +1. **A surprise in a review is always the supervisor's failure.** The review is where accumulated, already-delivered feedback is consolidated — never where it debuts. +2. **Assess, don't blend.** Write the full assessment first, then choose the few messages that change next year's output. Blending to make delivery comfortable makes the message incoherent. +3. **TRM is task-specific, and promotions reset it.** The org's best engineer was a beginner at the new task; structured management there was coaching, not condescension. +4. **Your ace deserves the most review effort, not the least.** "Keep it up" robs the top performer of their next level — and the coasting ace is usually a structure problem before it is an attitude problem. + +## Key Takeaways + +**1. Output is the only judge.** Every intervention above was scored the same way: did the organization's output rise? Meetings, indicators, reviews, and OKRs are machinery for that, not deliverables in themselves. + +**2. Measure before moralizing.** Dana's week log, the team's queue times, and Lena's written assessment all replaced a story ("I'm just busy", "we're faster", "he's difficult") with data — and the data redirected the fix every time. + +**3. Pair every number and forecast in the open.** Unpaired indicators manufactured the velocity crisis; stagger charts and paired dashboards cured it. Honesty is a system property before it is a virtue. + +**4. Style follows task-relevant maturity.** The same person needs structure on one task and autonomy on another, simultaneously. Most "people problems" in these cases were style-to-TRM mismatches wearing personality costumes. + +**5. Process meetings are where problems get caught small.** 1:1s with hold lists, staff meetings with debated topics, and operation reviews with honest trends starved the emergency meetings and the year-end detonations alike. diff --git a/.agents/skills/high-output-management/references/decisions-planning-okrs.md b/.agents/skills/high-output-management/references/decisions-planning-okrs.md new file mode 100644 index 00000000..c5ee92bb --- /dev/null +++ b/.agents/skills/high-output-management/references/decisions-planning-okrs.md @@ -0,0 +1,146 @@ +# Decisions, Planning, and OKRs + +## Table of Contents + +- [The Ideal Decision Process](#the-ideal-decision-process) +- [The Decision Brief: Six Questions](#the-decision-brief-six-questions) +- [The Lowest Competent Level](#the-lowest-competent-level) +- [Countering Peer-Group Syndrome](#countering-peer-group-syndrome) +- [The Three-Step Planning Process](#the-three-step-planning-process) +- [Writing OKRs Grove-Style](#writing-okrs-grove-style) +- [A Worked OKR Cascade](#a-worked-okr-cascade) +- [Pitfalls](#pitfalls) + +## The Ideal Decision Process + +Grove's model has three stages, in strict order, with no skipping: + +**1. Free discussion.** Every relevant view and fact gets on the table, including — especially — dissent. "Free" is literal: people argue the merits regardless of rank, half-formed worries are admissible, and the senior person's job is to *draw out* disagreement, not to win early. Two disciplines make it real: senior people speak last (the moment the boss leans, the discussion is over whether anyone admits it), and dissent is framed as an obligation, not a courtesy — staying silent in the discussion and critical in the hallway is the one unforgivable move. + +**2. Clear decision.** Discussion converges or time runs out; either way, the named decision-maker states the decision crisply, in writing, with the reasoning. Grove's observation: the more contentious the issue, the *more* unambiguous the wording must be, precisely because everyone is motivated to hear their preferred version. Vague decisions are the most expensive output a meeting can produce — everyone leaves to execute a different one. + +**3. Full support.** Everyone commits to the decision's success — *support*, not pretended agreement. "Disagree and commit" is honorable on both sides: the dissenter argued fully and now executes fully; the organization in turn owes them that the disagreement was genuinely heard. Relitigating in side channels is sabotage; reopening *openly* because material new facts arrived is management. The difference is the venue and the honesty. + +The three stages also define the failure modes: discussion without decision (the circling committee), decision without discussion (rank ruling on partial knowledge), and decision without support (the quiet veto in execution). + +## The Decision Brief: Six Questions + +Grove insisted a decision be framed *before* the meeting that makes it. Answer six questions in writing and attach them to the invite: + +``` +DECISION BRIEF + +1. What decision is needed? + One sentence, phrased as a question with identifiable options. +2. By when? + The real deadline and what it's anchored to (contract, launch, hiring window). +3. Who decides? + One name. Not a committee. +4. Who must be consulted before the decision? + The people whose knowledge or stake earns them input — with a date for it. +5. Who ratifies or can veto? + Usually the decider's manager; ratification checks blast radius, not taste. +6. Who must be informed after? + Everyone whose work changes because of the outcome. +``` + +**Worked example:** + +``` +1. Decision: Which payments provider for EU expansion — extend current + vendor, or migrate to Adyen? +2. By when: June 30 (contract renewal is July 15; migration lead time 6 weeks). +3. Who decides: Priya (platform PM). +4. Consulted: payments eng lead (integration cost), finance (fees model), + support lead (dispute tooling) — input by June 20. +5. Ratifies: VP Engineering (commits 2 engineers for a quarter if migrating). +6. Informed: checkout team, data team (settlement pipelines), exec staff. +``` + +The brief takes fifteen minutes to write and routinely saves weeks: half the time, writing it reveals the meeting is unnecessary (the decider can decide today), mis-staffed (the real consultations haven't happened), or premature (the deadline is invented). + +## The Lowest Competent Level + +Decisions should be made at the lowest level where someone has both the relevant technical grasp and acceptable judgment about consequences. Two reasons. First, knowledge currency: in fast-moving fields the people closest to the work hold the freshest technical truth; every level of escalation trades current knowledge for older generalizations. Second, speed and ownership: decisions made by the people who must execute them start with built-in commitment. + +When no single person has both halves, **compose the decision**: pair the engineer with the freshest technical knowledge and the manager carrying organizational judgment, and have them decide *together* — explicitly, as named co-deciders, not as "input" flowing upward to be overruled. Grove considered this blend of knowledge-power and position-power the everyday business of a well-run company. + +What escalates: decisions whose blast radius genuinely exceeds the local view (cross-org resource shifts, irreversible commitments, precedent-setting calls). What does not: decisions escalated because someone senior *would like* to make them. Each unnecessary escalation teaches the team that authority, not knowledge, decides — and the best people start pre-clearing everything, which is how organizations get slow. + +## Countering Peer-Group Syndrome + +Put six peers in a room with a contested question and watch: everyone hedges, nobody wants to stick out with a strong position that might lose, and the discussion circles — not because nobody knows, but because nobody wants to be *wrong in front of equals*. Grove named it peer-group syndrome, and its root is fear of looking dumb, which silences exactly the people with the most current knowledge. + +Counters, in order of power: + +- **Peer-plus-one.** Add one person senior to the group, sanctioned in advance to break ties and absorb the risk of the call. Their presence licenses strong positions: someone in the room can bless one. +- **The chairman states the question first.** Circling thrives on ambiguity about what is being decided. Opening with the decision brief's question collapses the fog. +- **Written positions before the meeting.** One paragraph from each participant, circulated with the pre-read. Positions taken in writing before social pressure exists are more honest, and the spread of views is visible immediately. +- **Senior people speak last** — and ask questions before stating views. +- **Assign the counter-case.** Name someone to argue the strongest version of the losing side, decoupling the argument from the arguer's reputation. +- **Reward visible mind-changing.** When someone updates on evidence, the senior person marks it as strength. Once changing your mind is safe, taking a position is too. + +## The Three-Step Planning Process + +Grove's planning frame, applicable to a yearly org plan or a quarter's team plan: + +**Step 1 — Environmental demand: what will be wanted of you?** Not what you want to build — what your environment (customers, adjacent teams who depend on you, the market, the company's direction) will demand of you over the planning horizon, typically the next one to two years. List the demands and their trajectory: growing, flat, fading. The discipline is *outside-in*: a platform team's environment is its internal customers' roadmaps; a product team's is the market and the support queue. + +**Step 2 — Present status: what are you producing now?** Current capabilities and trajectory, stated with uncomfortable honesty: what is actually shipping, what is in flight *and will genuinely finish*, what is in flight and will not (say so now, not in month eleven), and where capacity is actually going (run the leverage audit's numbers — firefighting and maintenance load included). + +**Step 3 — Close the gap.** The difference between step 1 and step 2 is the gap, and the plan is the set of *actions taken now* — projects started, projects killed, hires opened, skills built — to close it. Two Grove rules govern this step: + +- **The output of planning is decisions and actions, not documents.** A planning process that produces a deck and no changed behavior produced nothing. The test of a finished plan: what did we *start*, *stop*, and *commit to* this week because of it? +- **Today's gap reflects yesterday's planning failure.** If you are firefighting now, the fire was set by what last year's plan missed. Therefore plan for the *next* gap: today's actions affect output one to two years out. A plan addressed to this week's smoke is reaction wearing planning's clothes. + +**Worked sketch:** a platform team's environment scan shows three product teams shipping mobile features next year (demand: mobile-ready APIs, rising) and the company entering the EU (demand: data residency, new and hard). Present status: the API gateway is web-centric; one engineer understands the data layer; 40% of capacity goes to toil from a legacy queue system. Gap-closing actions decided now: kill the legacy queue this quarter (frees the 40%), open one hire with data-residency experience, start the gateway redesign in Q3 — and explicitly *not* pursue the internal analytics tool two teams asked for, with the refusal communicated and dated. That last item matters: a plan that declines nothing has decided nothing. + +## Writing OKRs Grove-Style + +Grove's management by objectives — which John Doerr carried from Intel to Google as OKRs — answers exactly two questions: + +1. **Where do I want to go?** The *objective*: directional, motivating, few in number. +2. **How will I pace myself to see if I am getting there?** The *key results*: measurable milestones, stated so you can answer "did I hit it?" with yes or no, **without argument**. + +Grove's rules of construction: + +- **Few objectives.** Two or three per level per cycle... and that is not a typo. Each objective you add steals attention from the others; an OKR set with seven objectives is a to-do list with ambitions. +- **Key results are verifiable, dated milestones**, not activities. "Engage with the migration project" is not a key result; "legacy queue serving 0% of production traffic by Nov 15" is. +- **Short cadence.** Quarterly objectives with a monthly look — the system exists to provide *feedback during the race*, not a grade after it. +- **Cascaded, not dictated.** One level's key results supply the next level's candidate objectives — but each team *writes its own*, and a healthy share of objectives flow bottom-up from the people closest to the work. Alignment comes from visibility and negotiation, not transcription. +- **A stretch instrument, not a contract.** Missing a genuinely ambitious key result while performing well is a fine outcome; hitting 100% of everything means the bar was set for safety. The review of a person weighs far more than their OKR scorecard — which is why OKRs must never be wired mechanically to compensation. + +## A Worked OKR Cascade + +**Company (quarter):** +- **Objective:** Make checkout the fastest in the mid-market segment. + - KR1: p95 checkout latency under 800ms (from 2.1s). + - KR2: Checkout conversion +2 points. + - KR3: Zero sev-1 incidents in the checkout path this quarter. + +**Platform team** (adopts KR1 as its objective — the cascade joint): +- **Objective:** Cut checkout p95 below 800ms. + - KR1: Payment-provider calls parallelized; sequential wait eliminated by Aug 15. + - KR2: Edge-cached session auth live in EU and US regions by Sep 1. + - KR3: Latency budget dashboard with per-service attribution adopted by all three checkout services by Jul 31. + +**Individual engineer** (adopts team KR1 as her objective): +- **Objective:** Eliminate sequential payment-call latency. + - KR1: Parallel orchestration design ratified in RFC review by Jul 10. + - KR2: Shipped behind a flag, 10% traffic, error rate within 0.1% of baseline by Aug 1. + - KR3: 100% rollout with p95 contribution under 300ms by Aug 15. + +Each level is written by its owner, each key result is a dated yes/no, and reading upward, any engineer can trace why her work matters to the company's quarter — Grove's definition of the system working. + +## Pitfalls + +| Pitfall | What it looks like | Correction | +|---------|--------------------|------------| +| OKRs wired to compensation | Objectives sandbagged to safely-hittable; stretch vanishes | Comp reviews weigh whole performance; OKR scores are one input at most, never a formula | +| 100% attainment celebrated | The bar was set where it couldn't be missed | Treat ~70-80% on genuine stretch as healthy; investigate perfect quarters like misses | +| Objective inflation | Six-plus objectives per team | Cap at three; the cut list is the strategy | +| Activity key results | "Work on", "support", "continue" | Rewrite as dated, verifiable outcomes | +| Cascade as dictation | Teams transcribe their slice from above | Each level writes its own; expect bottom-up objectives too | +| Set-and-forget | OKRs written in week 1, reread in week 13 | Monthly check against the stagger chart; re-forecast, don't re-write history | +| Decision relitigated in hallways | "Supported" decision quietly starved in execution | Name it: reopen openly with new facts, or commit — there is no third venue | +| Planning produces a binder | Beautiful deck, unchanged behavior | End planning with started/stopped/committed actions, owners, and dates | diff --git a/.agents/skills/high-output-management/references/indicators-and-production.md b/.agents/skills/high-output-management/references/indicators-and-production.md new file mode 100644 index 00000000..a21ec7ad --- /dev/null +++ b/.agents/skills/high-output-management/references/indicators-and-production.md @@ -0,0 +1,147 @@ +# Indicators and Production Principles for Software Teams + +## Table of Contents + +- [The Breakfast Factory, Translated](#the-breakfast-factory-translated) +- [Finding the Limiting Step](#finding-the-limiting-step) +- [Inspect at the Lowest-Value Stage](#inspect-at-the-lowest-value-stage) +- [Choosing Team Indicators](#choosing-team-indicators) +- [Pairing Indicators: Three Worked Examples](#pairing-indicators-three-worked-examples) +- [Leading vs Trend Indicators](#leading-vs-trend-indicators) +- [The Stagger Chart](#the-stagger-chart) +- [Running an Operation Review](#running-an-operation-review) +- [Measuring Administrative Work](#measuring-administrative-work) +- [Anti-Gaming Rules](#anti-gaming-rules) + +## The Breakfast Factory, Translated + +Grove opens the book with a waiter's problem: deliver a three-minute egg, buttered toast, and hot coffee to the table simultaneously, fresh, at acceptable cost. Everything in production is in that sentence — and everything in running a software team is too: + +| Breakfast factory | Software team | +|-------------------|---------------| +| The egg (longest, least flexible step) | The limiting step: code review queue, staging environment, the one person who knows the billing system | +| Toast must start before the order is certain | Build to forecast: hiring, capacity, and roadmaps start on predicted demand | +| Candle the eggs before boiling | Inspect specs and designs before the build, not after | +| Batch toast in the toaster's capacity | Batch reviews, interviews, deploys where setup cost dominates | +| The waiter can't watch the kitchen continuously | Black-box the work; cut windows into it with indicators | + +The discipline is to draw the team's actual production line — idea → spec → build → review → test → deploy → operate, or ticket → triage → fix → verify → close — and then manage the flow, not the individual heroics inside it. + +## Finding the Limiting Step + +The limiting step is the stage that is longest, most expensive, or hardest to scale. The whole flow should be built around it, because output equals the limiting step's throughput no matter how fast everything else runs. + +**Procedure:** + +1. **Draw the stages** of one unit of work from request to "alive in production." Six to eight boxes is the right altitude. +2. **Measure queue time at each boundary** for the last 20-30 units of work — time *waiting* between stages, not time being worked. Git timestamps, ticket histories, and PR metadata usually contain all of it. +3. **The stage with the longest queue in front of it is the limiting step.** Work piles up in front of constraints; that is the whole diagnostic. +4. **Verify with a thought experiment:** if this stage doubled its throughput, would the team's output rise? If yes, it is the constraint. If output would just pile up at the next stage, keep looking. + +**Then build around it:** + +- **Protect its capacity.** If review is limiting, reviewer hours are scheduled before new feature work, not squeezed after. +- **Stop starting work the constraint cannot absorb.** A WIP limit upstream of the limiting step is the software equivalent of not cracking eggs you cannot boil. +- **Offload it.** Move work off the constraint: linters and CI take mechanical findings off reviewers; templates take routine answers off the senior engineer. +- **Re-find it quarterly.** Constraints move once relieved. Teams that "fixed review" in Q1 are often staging-limited by Q3. + +## Inspect at the Lowest-Value Stage + +A flaw costs more at every stage it survives. The rule: detect and fix any problem at the lowest-value stage possible. + +| Stage caught | Typical cost to fix | +|--------------|---------------------| +| One-page spec review | An hour and a conversation | +| Design/RFC review | A day and a revision | +| PR review | Days — code exists, sunk cost argues back | +| QA / staging | A week — context reload, retest | +| Production incident | Weeks — plus customers, trust, and on-call burnout | + +Three kinds of inspection, mapped from the factory: + +- **Incoming inspection:** requirements and specs. Is the problem real, the approach sound, the scope bounded? The cheapest hour in engineering is the hour spent killing a bad spec. +- **In-process inspection:** design reviews, PR review, CI. Catch flaws while the material is still cheap to rework. +- **Final inspection:** release checklists, canary deploys, smoke tests. Necessary, but if final inspection is your primary quality mechanism, you have built a factory that ships rotten eggs to the plating station. + +Choose between **gate** (work stops until it passes — right for irreversible or high-blast-radius changes: schema migrations, auth, billing) and **monitoring** (work proceeds, samples are checked, drift triggers tightening — right for everything else, because gates everywhere destroy flow). A useful default: gates at incoming and final, monitoring in process — tightened temporarily where escapes have actually occurred, then loosened again. A variable-inspection scheme beats permanent maximum inspection. + +## Choosing Team Indicators + +Indicators are the windows cut into the black box. Choosing them well: + +1. **Four to six, no more.** Beyond that, attention diffuses and nobody steers. +2. **Each measures output or a direct precondition of output** — not effort, not motion. +3. **Each has an owner and a review cadence** (the weekly team review and the monthly operation review below). +4. **Each quantity indicator gets a quality pair** — this is non-negotiable, because people will do what management measures, and an unpaired number is an instruction to game it. +5. **Cheap to collect.** An indicator that takes an afternoon to assemble dies in a month. Pull from systems (git, CI, ticketing, observability), not from human memory. + +## Pairing Indicators: Three Worked Examples + +**1. Code review throughput vs defect escape rate.** +A platform team measured time-to-first-review (median 26 hours) and made it the headline metric. Within six weeks the median fell to 4 hours — and rubber-stamp approvals rose with it; "LGTM" reviews with zero comments went from 18% to 55%, and bugs found after merge climbed. The fix was the pair: *PRs reviewed per week* and *time-to-first-review* displayed only alongside *defect escape rate* (bugs attributed to merged PRs per 100 merges, found within 30 days). Reviewers could no longer win by waving work through; the pair forced the real goal — fast *and* sound review. Stabilized at 8-hour first response with escapes at half the original rate. + +**2. Ticket closes vs reopen rate.** +A support team paid attention (and a spiff) to tickets closed per agent-day. Closes rose 30%; so did "resolved" tickets that customers immediately reopened — agents were closing on first response with a boilerplate answer. Pairing *closes per agent-day* with *reopen rate within 7 days* and *CSAT on closed tickets* exposed the pattern in the first week: the two agents with the highest close counts had the worst reopen rates. Coaching, not punishment, followed — and the indicator pair was published to the team so everyone could see that the game had changed from "close fast" to "close once." + +**3. Feature velocity vs incident rate.** +A product team celebrated rising velocity (story points per sprint, up 40% over two quarters). The same period: change-failure rate doubled, two sev-2 incidents per month became five, and on-call escalations rose. Velocity was being purchased with skipped tests and deferred migrations — invisible because nobody graphed the pair. The fix: a four-indicator dashboard — *features shipped per sprint*, *change-failure rate*, *incidents attributed to recent changes*, *p95 cycle time* — reviewed together in the monthly operation review. Velocity dropped 15% the next quarter; incidents fell by two-thirds; net output (features alive and stable in production) rose. + +The general law: any indicator pushed hard will be achieved — the only question is what gets sacrificed to achieve it. The pair makes the sacrifice visible before the customer reports it. + +## Leading vs Trend Indicators + +**Leading indicators** let you act before output falls. Good ones for software teams: review queue age, build flakiness rate, on-call pages per week, backlog age of sev-2 bugs, recruiting pipeline depth, and a simple morale pulse. Each needs a believed threshold — a level at which you have pre-committed to act, otherwise you will explain away the warning ("the linearity index dipped, but surely it'll catch up"). + +**Trend indicators** show output against two baselines: your own history (deploys this month vs the last six) and your forecast (what you said you would do). Measurement against forecast is what turns an indicator from a mood into a commitment — which is the stagger chart's job. + +## The Stagger Chart + +A stagger chart re-forecasts the same horizon every period, keeping every previous forecast visible. Forecast the next three sprints' completed scope (or the quarter's ARR, or the month's hiring), and each period add a new row: + +| Forecast made | Sprint 10 | Sprint 11 | Sprint 12 | Sprint 13 | +|---------------|-----------|-----------|-----------|-----------| +| In sprint 9 | 24 pts | 26 | 27 | — | +| In sprint 10 | **21 (actual)** | 24 | 26 | 27 | +| In sprint 11 | | **20 (actual)** | 23 | 26 | +| In sprint 12 | | | **22 (actual)** | 24 | + +Read **down a column**: sprint 12 was forecast at 27, then 26, then 23, landing at 22. The team systematically over-forecasts by ~20% — visible in one glance, unarguable, and correctable. A team that sandbaggs shows the opposite signature (forecasts rising to meet comfortable actuals). The stagger chart does not punish misses; it makes forecast *bias* a measured, improvable quantity — which is the honest foundation under every commitment the team makes outward. + +## Running an Operation Review + +The operation review is where indicators meet an audience: managers present their area to people who do not see their work day-to-day — adjacent teams, skip-levels, new hires. Grove's purposes: it teaches, it motivates (people raise their game when their work has an audience), and it lets seniors sanity-check trends juniors might rationalize. + +**Cast:** an *organizing manager* (logistics, agenda, timekeeping), a *reviewing manager* (senior; asks questions, sets the tone, never ambushes), 2-4 *presenters* (line managers/leads with their indicators), and the *audience* — whose job is to engage, not spectate. + +**Cadence:** monthly for a department, quarterly for an org. Sixty to ninety minutes. + +**Agenda template:** + +1. (5 min) Reviewing manager: why we are here, what changed since last time. +2. (15 min × 3) Each presenter: their 4-6 indicators as *trends with forecasts* (stagger charts, not snapshots), one problem they are working, one ask of the room. +3. (10 min) Open questions across areas — the cross-pollination is the point. +4. (5 min) Reviewing manager: themes, decisions taken, actions with owners. + +**Presenter rules:** trends, not points-in-time; pairs shown together; misses stated before anyone asks; no slide with more than one chart. **Reviewing-manager rules:** ask the second question ("what's underneath that?"), praise honest bad news, and never let the room punish a candid miss — one ambushed presenter converts the whole org's reviews into theater permanently. + +## Measuring Administrative Work + +Grove insisted administrative and knowledge work be measured like production, because it is production: + +| Function | Output indicator | Quality pair | +|----------|------------------|--------------| +| Recruiting | Offers extended per week | Offer-accept rate; 90-day retention of hires | +| Support | Tickets resolved per agent-day | Reopen rate; CSAT | +| Documentation | Docs shipped/updated per month | Search success rate; support tickets on documented topics | +| Finance ops | Invoices processed per day | Error/dispute rate | +| IT/internal tools | Requests fulfilled per week | Repeat-request rate; requester satisfaction | + +Same rules as engineering indicators: output not activity, paired, owned, trended against forecast. + +## Anti-Gaming Rules + +- **Publish the pair or publish nothing.** A quantity indicator released alone is a gaming instruction with a dashboard. +- **Indicators describe the work, not the worker.** Use team-level indicators for steering; individual performance is assessed in reviews with full context, not read off a throughput chart. The moment indicators become surveillance, people optimize the number and hide the truth — and you lose both the output and the warning system. +- **Never convert an indicator directly into compensation.** The instant money attaches, the indicator stops measuring reality (see the OKR pitfalls in [decisions-planning-okrs.md](decisions-planning-okrs.md)). +- **Expect Goodhart drift and rotate emphasis.** Any measure pushed for quarters degrades; re-derive indicators from the current limiting step, not from habit. +- **Let the team see everything you see.** Indicators reviewed in the open steer; indicators reviewed privately breed paranoia and creative accounting. diff --git a/.agents/skills/high-output-management/references/leverage-and-calendar.md b/.agents/skills/high-output-management/references/leverage-and-calendar.md new file mode 100644 index 00000000..bd88d3ce --- /dev/null +++ b/.agents/skills/high-output-management/references/leverage-and-calendar.md @@ -0,0 +1,139 @@ +# Managerial Leverage and the Calendar + +## Table of Contents + +- [The Output Equation](#the-output-equation) +- [Step 1: Log a Real Week](#step-1-log-a-real-week) +- [Step 2: Classify Every Block](#step-2-classify-every-block) +- [Step 3: Score the Leverage](#step-3-score-the-leverage) +- [The Leverage Catalog](#the-leverage-catalog) +- [The Delegation Protocol](#the-delegation-protocol) +- [Monitoring Depth by Task-Relevant Maturity](#monitoring-depth-by-task-relevant-maturity) +- [Redesigning the Calendar](#redesigning-the-calendar) +- [Managing Interruptions](#managing-interruptions) +- [The Weekly Re-Audit](#the-weekly-re-audit) + +## The Output Equation + +A manager's output is the output of their organization plus the output of the neighboring organizations under their influence. Nothing on the calendar has value in itself — a meeting, a review, an approval matters only through the output it eventually creates or destroys. Leverage is the exchange rate: output created per unit of managerial time spent on an activity. + +Three ways to raise output follow directly: + +1. **Speed up** — do the same activities faster (helps a little, caps quickly). +2. **Raise the leverage of existing activities** — better preparation, better timing, bigger audiences for the same hour. +3. **Shift the mix** — replace low- and negative-leverage activities with high-leverage ones. This is where almost all of the gain lives, and it is what the audit below finds. + +The audit takes one logged week and roughly ninety minutes of analysis. Most managers who run it discover that 30-50% of their week is spent on activities that either anyone could do, that nobody should do, or that actively subtract output. + +## Step 1: Log a Real Week + +Log five working days at 30-minute granularity. Rules that keep the data honest: + +- **Log as you go, classify later.** Classifying while logging biases what you record. +- **Log what actually happened**, not what the calendar said. The 9:00 "deep work block" that became forty minutes of Slack is logged as Slack. +- **Mark interruptions with a tally**, not a block. Six pings inside one hour is its own finding. +- **Note who else was present** for every meeting — you will need headcount for cost math later. +- **Pick a typical week.** Not launch week, not the week after reorg. If no week is typical, log two. + +A spreadsheet with four columns is enough: time, what, who, interrupt count. + +## Step 2: Classify Every Block + +Grove's insight is that all managerial activities reduce to a small set. Tag each block with one of: + +| Type | What it looks like | Notes | +|------|--------------------|-------| +| **Information gathering** | 1:1s, reading reports and dashboards, hallway/Slack conversations, customer calls, reading code or tickets | The base activity — everything else depends on its quality. Verbal sources are fastest but vaguest; written reports discipline the writer more than they inform the reader | +| **Information giving** | Announcements, briefings, documentation, answering questions, setting context in meetings | Includes conveying not just facts but objectives, priorities, and preferred ways of doing things | +| **Decision-making** | Choosing vendors, approving designs, allocating people, setting priorities — or participating in someone else's decision | Split "made the decision" from "sat in a meeting where a decision happened to me" | +| **Nudging** | Suggesting a direction without ordering it: a comment in a design review, a question in a planning doc | Legitimate and distinct from deciding — you nudge many times a day | +| **Being a role model** | Visible behavior: how you run meetings, handle incidents, treat people, write | Values transmit through observed behavior, never through speeches. You are doing this all day whether you intend to or not | + +Anything that fits none of these — doing IC work, expediting a ticket, formatting a slide — gets tagged **doing**, and becomes a delegation candidate in Step 3. + +## Step 3: Score the Leverage + +Now score each block high, neutral, or negative. The test for each: + +- **High leverage:** one hour affects many people's output (training, a well-run staff meeting, hiring), affects one person's output for a long time (a prepared review, a career conversation, an early spec read), or affects a large body of work through perfect timing (catching a wrong design before the build starts). +- **Neutral:** necessary, output-preserving, low multiplication — expense approvals, routine syncs, most email. +- **Negative leverage:** the hour subtracted output from others. See the catalog below. + +Then compute three numbers: percentage of week in high-leverage work, in "doing", and in negative leverage. Typical first-audit results for a new engineering manager: 15% high, 35% doing, 10% negative, the rest neutral. Target after redesign: 40%+ high, under 10% doing, zero tolerated negative. + +## The Leverage Catalog + +**Reliably high-leverage activities:** + +- **Training you deliver yourself** — Grove's arithmetic: four lectures taking ~12 hours of preparation, delivered to ten people who will work ~20,000 hours in the next year. A 1% improvement buys 200 hours of output for a dozen hours of work. +- **Performance reviews prepared properly** — one written assessment steers a year of one person's output. +- **1:1s** — ninety minutes can raise the quality of a subordinate's work for two weeks or more. +- **Writing once for many readers** — a decision memo, an onboarding doc, a postmortem; the alternative is explaining it eleven times. +- **Early-stage inspection** — an hour on a one-page spec saves a month on a wrong build. +- **Hiring** — few hours have a longer half-life. +- **The timely nudge** — one question in the right design review redirects a quarter of work. + +**Negative-leverage activities (each hour subtracts):** + +- **Meddling** — supervising in detail a person who has high task-relevant maturity for the task. The expert slows down, stops owning outcomes, and learns to wait for instructions. +- **Waffling** — sitting on a decision others are blocked on. Ten people idling for three days is a costlier purchase than almost anything you could buy with a PO. +- **Mood contagion** — a manager's visible anxiety or gloom propagates; the team spends its energy reading you instead of building. +- **The unprepared meeting** — eight people discovering the agenda live. +- **Being the approval bottleneck** — sign-offs queueing behind your travel schedule. +- **Last-minute review** — "fixing" finished work that should have been inspected at the spec stage; you pay full rework cost and demoralize the author. + +## The Delegation Protocol + +Delegation is how "doing" hours convert to high-leverage hours — but delegation without monitoring is abdication, and silent re-grabbing is worse. The protocol: + +1. **Pick what to delegate: the tasks you know best.** This feels backwards and is not. Monitoring is cheap when you can judge the work at a glance; delegating what you understand least means you cannot supervise it at all. Your famous-for tasks are your best handoffs. +2. **Hand off outcomes, not steps.** State the output expected, the constraints (budget, deadline, interfaces), and the quality bar. Put it in writing — two paragraphs, not a contract. +3. **Agree on the monitoring plan in the handoff conversation.** Checkpoint cadence, what gets sampled, what triggers escalation. Monitoring announced up front is quality assurance; monitoring imposed after a stumble is punishment. +4. **Monitor at the task level, not the person level.** You are sampling work products — plans, PRs, dashboards — the way a factory samples incoming material, not auditing the human. +5. **Vary depth with task-relevant maturity** (table below), and loosen visibly as results come in. +6. **Never take a task back silently.** If it is going wrong, say so, raise monitoring frequency, add training — and if you must repossess it, do it explicitly with reasons. Quiet repossession teaches the team that delegation is a trap. + +## Monitoring Depth by Task-Relevant Maturity + +| Subordinate's TRM for this task | What you review | Cadence | Style | +|---------------------------------|-----------------|---------|-------| +| **Low** (new to task, regardless of seniority) | The plan before work starts, then work products at each stage | 2-3 times/week, scheduled | Structured: what, when, how; short feedback loops | +| **Medium** (done it with help before) | The plan plus spot-checks of in-progress work | Weekly | Mutual reasoning: what and why; they propose, you probe | +| **High** (done it well repeatedly) | Final outputs and a few agreed indicators | At milestones / monthly | Objectives only; monitor outcomes, intervene on request or on indicator drift | + +Re-rate TRM whenever the task changes. The engineer who is high-TRM on service migrations may be low-TRM on their first vendor negotiation — and your monitoring must change with them, in both directions. + +## Redesigning the Calendar + +Treat the calendar as a production system and apply factory rules to it: + +1. **Forecast the limiting steps first.** The high-leverage fixed events — 1:1s, staff meeting, planning, reviews, training you teach — go on the calendar before anything else, like the egg timer everything else offsets from. These are commitments others schedule around; they move only for emergencies. +2. **Batch similar work.** Group PR reviews into one or two daily windows, interviews into two afternoons, email into two or three passes. Every context switch is a setup cost; batching amortizes it. +3. **Create maker blocks and defend them.** Two or three half-days of focus time, treated like meetings with yourself. Your reports' maker time deserves the same defense — audit how many of their interruptions are you. +4. **Leave slack.** Keep roughly 15% of the week unscheduled. A manager at 100% utilization is a server at 100% utilization: every arrival queues, and latency explodes for everyone downstream. +5. **Say no at the source.** Capacity planning means refusing or renegotiating work beyond capacity at the moment it is offered — "yes, after the planning cycle" or "no, and here is who can" — rather than accepting it into a queue where it will silently rot. +6. **Use the cost test on every standing meeting you own.** Attendees × hours × loaded hourly rate. An eight-person hour costs about a thousand dollars; if you would not sign a purchase order for that amount for the value produced, restructure or kill it. + +A redesigned week for an EM with six reports might look like: Monday — maker block AM, staff meeting after lunch, batched reviews 4pm; Tuesday/Wednesday — 1:1s in morning blocks, office hours 2-3pm; Thursday — interviews batched PM; Friday — planning/indicator review, maker block, slack. + +## Managing Interruptions + +Interruptions are demand arriving at random for a resource (you) that performs best in batches. Apply production thinking rather than heroics: + +- **Count them first.** The week log's tally marks show who interrupts, about what, and when. Most managers find 60%+ of interrupts come from a handful of question types. +- **Export the answers.** Recurring questions become a FAQ, a runbook, a dashboard, or a trained delegate. Answering the same question eleven times is a documentation failure, not diligence. Each written answer is a small machine that works while you sleep. +- **Batch the rest with office hours.** Two predictable daily slots convert random arrivals into a queue with a known service time. Pair with the 1:1 hold list: "great question — put it on the hold list for Tuesday" is a complete, polite sentence. +- **Publish an escalation ladder.** Define what justifies an immediate page (production down, customer-visible failure, a person in trouble) versus the next office hours versus the next 1:1. People interrupt randomly when they cannot predict what you consider urgent. +- **Do not go dark.** The goal is batching, not unavailability — an unreachable manager simply trains people to make uninformed decisions in private. + +## The Weekly Re-Audit + +The full audit is occasional; this five-minute version runs every Friday: + +1. What fraction of my hours this week were high-leverage? (Target: rising toward 40%.) +2. What did I do that someone on the team could now do — and what training or delegation would make that true next month? +3. Where did I create negative leverage — a delayed decision, a meddled task, a mood I broadcast — and what is the repair? +4. Which interrupt should become a document, a delegate, or a hold-list item? +5. Is next week's calendar forecast — 1:1s, maker blocks, batches — already in place, or will the week happen to me again? + +Write the answers down; four weeks of them is its own stagger chart of whether your management is trending toward output. diff --git a/.agents/skills/high-output-management/references/meetings-and-one-on-ones.md b/.agents/skills/high-output-management/references/meetings-and-one-on-ones.md new file mode 100644 index 00000000..4159f9f8 --- /dev/null +++ b/.agents/skills/high-output-management/references/meetings-and-one-on-ones.md @@ -0,0 +1,159 @@ +# Meetings and One-on-Ones: The Full Playbook + +## Table of Contents + +- [Two Species of Meetings](#two-species-of-meetings) +- [The One-on-One](#the-one-on-one) +- [Frequency by Task-Relevant Maturity](#frequency-by-task-relevant-maturity) +- [The Subordinate's Agenda](#the-subordinates-agenda) +- [The Hold List](#the-hold-list) +- [Notes, "One More Thing", and Remote 1:1s](#notes-one-more-thing-and-remote-11s) +- [The Staff Meeting](#the-staff-meeting) +- [The Operation Review](#the-operation-review) +- [Mission-Oriented Meetings](#mission-oriented-meetings) +- [Meeting-Cost Math and When to Kill a Meeting](#meeting-cost-math-and-when-to-kill-a-meeting) + +## Two Species of Meetings + +Grove's claim is blunt: a meeting is the *medium* through which most managerial work — gathering and giving information, making decisions, nudging — is performed. You cannot oppose meetings any more than a carpenter can oppose hammers; you can only run good ones or bad ones. + +- **Process-oriented meetings** run on a regular cadence with a known format: one-on-ones, staff meetings, operation reviews. Regularity is what makes them cheap — agendas are standing, expectations shared, setup cost near zero — and what makes them effective: problems get caught while they are small. +- **Mission-oriented meetings** are ad hoc and exist to produce one specific decision. They are expensive by nature (interrupt-driven, unprepared attendees, no standing format). + +The design goal: process meetings carry the bulk of managerial work — on the order of a quarter of a manager's calendar — so that mission-oriented meetings become rare. Grove's malorganization test: if ad hoc mission-oriented meetings consume more than about 25% of a manager's time, the regular process is failing. And the corollary diagnostic: **any "ad hoc" meeting that keeps recurring is a process meeting in denial** — give it a cadence, a format, and a standing agenda, and its cost collapses. + +## The One-on-One + +The 1:1 is a regular, scheduled meeting between a supervisor and one subordinate, and it is **the subordinate's meeting**: their agenda, their airtime, their problems. Its purposes: mutual teaching (the supervisor shares context and skills; the subordinate teaches the supervisor what is really going on below), exchange of information too awkward or early for any other forum, and the supervisor's single best source of organizational knowledge. + +Grove's leverage math: ninety minutes of your time can enhance the quality of your subordinate's work for two weeks — eighty-plus working hours. There is no cheaper multiplier on the calendar, which is why "too busy for 1:1s" inverts the economics: the busier the period, the more the 1:1 pays. + +Baseline mechanics: + +- **Length:** an hour as the default. Anything shorter, Grove observed, makes the subordinate confine themselves to simple things; the hard topics need room to surface. 45 minutes is the floor for a working cadence; never 15. +- **Setting:** the subordinate's turf or neutral ground, not a summons to your office. Remote: cameras on, both in a shared doc. +- **Scheduling:** rolling and protected. Reschedule within the week when needed; cancellation is reserved for true emergencies, because each silent drop teaches the report their problems can wait. + +## Frequency by Task-Relevant Maturity + +Set frequency per person by their task-relevant maturity on their *current* work — not by seniority, tenure, or how much you enjoy the conversation: + +| Situation | Frequency | Length | +|-----------|-----------|--------| +| New to role, project, or domain (any seniority) | Weekly | 60 min | +| Ramping: competent with support, task still changing | Every two weeks | 45-60 min | +| Veteran on stable scope, strong indicators | Every three to four weeks | 60 min | +| Anyone during a crisis, reorg, or major task change | Snap back to weekly | 60 min | + +Re-rate at every task change. The principal engineer who just became a manager is low-TRM again; the weekly cadence returns even though they are your most senior person. When in doubt, err frequent — over-meeting costs an hour; under-meeting costs a surprise in month three. + +## The Subordinate's Agenda + +The subordinate prepares and sends the agenda the day before. Preparing it is itself the point — it forces them to survey their own work, spot trouble early, and decide what matters. A copy-paste template: + +``` +1:1 — / , + +1. Indicators since last time: what moved, what I think it means +2. Wins and what's finished +3. Problems and blockers — current, and ones I can smell coming + ("anything that bothers me", half-formed worries explicitly welcome) +4. Plans: what I intend to do next, decisions I'm about to make +5. Hold-list items (accumulated small topics) +6. Career / growth / feedback item (at least monthly) +7. Manager's items (last, and they don't get to eat the hour) +``` + +Two supervisor rules. First, items 3 and 4 are where you earn your keep: the subordinate talks, you ask the *second* question — "what's underneath that?", "what would have to be true?", "what happens if it slips?" — until the real shape of the problem is on the table. Second, your own topics ride in seat 7. The fastest way to kill a 1:1 program is to convert it into a status extraction or a tasking session; reports stop bringing problems and start bringing performances. + +## The Hold List + +Both parties keep a running list — paper, doc, or DM-to-self — of topics that are important but not urgent, batched for the next 1:1. Effects: interruptions drop on both sides (most "got a sec?" pings are hold-list items in disguise), small items actually get handled instead of evaporating, and the 1:1 always has a floor of concrete material. "Put it on the hold list" is the polite, complete answer to most non-urgent pings — and modeling it teaches the team to batch their interruptions of each other, too. + +## Notes, "One More Thing", and Remote 1:1s + +**The supervisor takes the notes**, on the subordinate's agenda, during the meeting. Writing while they talk signals that what they said registered and will be acted on; the written trail forces follow-up on both sides. End by reading back the actions: who does what by when. Next meeting opens with that list. + +**"One more thing."** When the agenda is exhausted and chairs start to push back, ask: *"What else is on your mind?"* — and wait through the pause. The genuinely important item — the resignation being considered, the conflict with a peer, the doubt about the project — surfaces disproportionately in the last five minutes, after trust has warmed and the formal agenda no longer protects it. Budget for this; ending a 1:1 ten minutes "early" without asking is leaving the most valuable item in the room. + +**Remote 1:1s.** The agenda doc is open on both screens and notes are typed into it live — Grove's "both looking at the same paper", updated. Cameras on if at all possible; notifications off (a glance at Slack reads as "you don't matter" at distance). Because hallway leakage is zero remotely, the hold list and the "one more thing" question carry even more of the load — skip neither. + +## The Staff Meeting + +The staff meeting is the supervisor plus all direct reports, weekly, 60-90 minutes. Its special value: it is where the manager watches and shapes how their reports interact with *each other*, and where issues touching two or more people get settled with everyone present. + +The format Grove prescribed is **controlled free discussion**: more structured than a bull session, looser than a briefing. The manager's role is moderator — Socratic prodder — not lecturer. If the manager talks more than a quarter of the time, it has become a broadcast, which email does cheaper. + +Copy-paste agenda: + +``` +Staff meeting — , weekly, 60 min + +1. (5) Metrics minute: the team's 4-6 indicators on screen; anomalies flagged only +2. (10) Round: one minute each — top priority, top worry. No narration of the week +3. (35) Two or three debated topics, flagged in advance by anyone on the team: + decisions touching 2+ people, cross-cutting risks, contested priorities. + Owner states the question; manager moderates; end each with + decision / owner / date, or an explicit "decide by with " +4. (5) Announcements that genuinely can't be written down +5. (5) Actions read back +``` + +Rules: anything that concerns only one person moves to that person's 1:1; status that can be written, is written; "open issues" without an owner do not survive the meeting. The debated-topics slot is the heart — it is where the manager teaches decision-making by moderating instead of pronouncing. + +## The Operation Review + +The operation review is the periodic formal forum — monthly for a department, quarterly for an org — where line managers present their indicators and trends to people who do not see their work daily: adjacent teams, skip-level management, newer employees. It teaches, it cross-pollinates, and it motivates: work that will have an audience gets finished differently. + +Four roles, each with a job: + +- **Organizing manager:** owns logistics, picks presenters, enforces the clock, circulates pre-reads 48h ahead. +- **Reviewing manager** (the senior person): sets the tone, asks the questions juniors won't, sanity-checks trends — and *never ambushes*. Their most important behavior: visibly rewarding honest bad news. +- **Presenters** (2-4 line managers/leads): show trends and forecasts, not snapshots; show indicator pairs together; state misses before being asked; bring one problem and one ask. +- **Audience:** obligated to engage — questions are the mechanism. A silent audience converts the review into theater. + +Copy-paste agenda (75 min): + +``` +Operation review — , monthly + +1. (5) Reviewing manager: context; follow-ups from last review +2. (3 × 15) Presenters: indicator trends vs forecast (stagger charts), + one problem being worked, one ask of the room +3. (15) Cross-area questions and discussion +4. (10) Reviewing manager: themes, decisions, actions with owners +``` + +## Mission-Oriented Meetings + +When an ad hoc meeting truly is needed, it exists to produce a decision, and it has a **chairman** — the person who called it — with non-delegable duties: + +- Name, in the invite, the decision to be made and by when. +- Invite the necessary people only — for a decision discussion, six or seven is the ceiling; beyond that, people watch instead of deciding. +- Send the pre-read 24h ahead; open by restating the question, not by reading the deck. +- Close with the decision stated in one sentence, plus owner and date — or an explicit deferral naming what information will settle it and when. +- Send the one-paragraph summary the same day. + +If the meeting could not state its decision in the invite, it was an information meeting wearing a costume — handle it in writing or fold it into a process meeting. And if you are scheduling substantially the same "ad hoc" meeting for the third time, stop: give it a cadence and a standing format, and it becomes cheap. + +## Meeting-Cost Math and When to Kill a Meeting + +Grove's framing: a manager's time has a real dollar value, and calling a meeting is spending it — an unplanned meeting is an unplanned purchase order. Make the math explicit: + +``` +cost = attendees × duration (h) × loaded hourly rate +``` + +Ten people × one hour × $130 loaded ≈ $1,300 — roughly a new laptop per occurrence, $67k per year if weekly. The test for any standing meeting: *would you sign a purchase order for this amount, for what this meeting produced last month?* + +Kill, shrink, or convert when: + +| Signal | Action | +|--------|--------| +| No decision, surfaced problem, or changed plan in the last 3 occurrences | Kill it; replace with a written update | +| Half the room never speaks | Shrink the list; minutes to the rest | +| Same two people do all the talking | Make it their 1:1 or a working session | +| Purely one-way status | Convert to a dashboard or memo; reclaim the hour | +| "We've always had it" is the only defense | Cancel for a month; reinstate only what is actually missed | + +Run a quarterly meeting audit: list every standing meeting you own, compute each one's annual cost, and re-justify it against what it produces. Default for borderline cases is cancellation — a genuinely needed meeting announces itself by the problems that appear in its absence, and it can always be reinstated leaner. diff --git a/.agents/skills/high-perf-browser/SKILL.md b/.agents/skills/high-perf-browser/SKILL.md new file mode 100644 index 00000000..7ae6e321 --- /dev/null +++ b/.agents/skills/high-perf-browser/SKILL.md @@ -0,0 +1,206 @@ +--- +name: high-perf-browser +description: 'Optimize web performance through network protocols, resource loading, and browser rendering internals. Use when the user mentions "my site is slow", "Core Web Vitals", "HTTP/2 or HTTP/3", "resource hints", "network latency", "render blocking", "TCP/TLS optimization", "service worker", "Cache-Control or caching strategy", or "critical rendering path". Also trigger when diagnosing slow page loads, optimizing time to first byte, choosing between WebSocket and SSE, or reducing bundle sizes. For UI visual performance, see refactoring-ui. For font loading, see web-typography.' +license: MIT +metadata: + author: wondelai + version: "1.4.1" +--- + +# High Performance Browser Networking Framework + +A systematic approach to web performance grounded in how browsers, protocols, and networks actually work. Apply these principles when building frontend applications, setting performance budgets, configuring servers, or diagnosing slow page loads. + +## Core Principle + +**Latency, not bandwidth, is the bottleneck.** Most web performance problems stem from too many round trips, not too little throughput. A 5x bandwidth increase yields diminishing returns; a 5x latency reduction transforms the user experience. + +**The foundation:** Every request passes through DNS resolution, TCP handshake, TLS negotiation, and HTTP exchange before a single byte of content arrives — each step adding round-trip latency. High-performance applications minimize round trips, parallelize requests, and eliminate unnecessary network hops. Understanding the protocol stack is the prerequisite for meaningful optimization. + +## Scoring + +**Goal: 10/10.** Score by how many of the eight Quick Diagnostic rows pass, weighted toward the field metrics: **9-10** = all eight pass (the four field-metric rows in the green plus content-hashing, HTTP/2+, minimized render-blocking, and compression); **5-6** = the four field-metric rows pass but one or more transport/caching/compression rows fail; **<=3** = any field-metric row is in the red. Always report the score, which diagnostic rows failed, and the specific fix for each. + +## The High Performance Browser Networking Framework + +Six domains for building fast, resilient web applications: + +### 1. Network Fundamentals + +**Core concept:** Every HTTP request pays a latency tax — DNS lookup, TCP three-way handshake, TLS negotiation — before any application data flows. Reducing or eliminating these round trips is the single highest-leverage optimization. + +**Why it works:** Light travels at a finite speed: a New York–London packet takes ~28ms one way regardless of bandwidth. These physics-level constraints cannot be solved with bigger pipes — only with fewer trips. + +**Key insights:** +- TCP three-way handshake adds one full RTT before data transfer begins +- TCP slow start limits initial throughput to ~14KB (10 segments) in the first round trip — keep critical resources under this threshold +- Upgrade to TLS 1.3: it halves the handshake round trips of TLS 1.2 and enables 0-RTT resumption for returning visitors +- Head-of-line blocking in TCP means one lost packet stalls all streams on that connection +- Bandwidth-delay product caps in-flight data; high-latency links underutilize bandwidth + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Connection warmup** | Pre-establish connections to critical origins | `` | +| **DNS prefetch** | Resolve third-party domains early (saves 20-120ms) | `` | +| **TLS optimization** | TLS 1.3 + session resumption | `ssl_protocols TLSv1.3;` with session tickets | +| **Connection reuse** | Keep-alive avoids repeated handshakes | `Connection: keep-alive` (default in HTTP/1.1+) | + +See [references/network-fundamentals.md](references/network-fundamentals.md) when tuning servers or diagnosing handshake latency — the full TLS 1.2-vs-1.3 RTT derivation, slow-start doubling table, initcwnd/BDP math, OCSP-stapling Nginx config, and the DNS cache hierarchy. + +### 2. HTTP Protocol Evolution + +**Core concept:** HTTP evolved from a simple request-response protocol into a multiplexed, binary system. Choosing the right protocol version and configuring it properly eliminates entire categories of performance problems. + +**Why it works:** HTTP/1.1 forces workarounds (domain sharding, sprites, concatenation) because it cannot multiplex. HTTP/2 multiplexes but inherits TCP head-of-line blocking; HTTP/3 (QUIC over UDP) eliminates it. Each generation removes a bottleneck — and makes the previous generation's workarounds counterproductive. + +**Key insights:** +- HTTP/1.1 allows one outstanding request per TCP connection; browsers open 6 per host as a workaround +- HTTP/2 multiplexes unlimited streams over one connection — domain sharding becomes counterproductive +- HPACK header compression in HTTP/2 cuts repetitive header overhead by 85-95% +- HTTP/3 (QUIC) eliminates TCP head-of-line blocking and enables 0-RTT resumption and connection migration +- Prefer `103 Early Hints` over HTTP/2 Server Push (which over-pushes and is widely deprecated) +- Connection coalescing lets one HTTP/2 connection serve multiple hostnames sharing a certificate + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **HTTP/2 migration** | Remove HTTP/1.1 workarounds | Undo domain sharding, sprites, file concatenation | +| **103 Early Hints** | Send preload hints before the full response | `103` with `Link: ; rel=preload` | +| **QUIC/HTTP/3** | Advertise HTTP/3 on CDN or origin | `Alt-Svc: h3=":443"` header | +| **Stream prioritization** | Signal resource importance | CSS and fonts highest priority; images lower | + +See [references/http-protocols.md](references/http-protocols.md) when picking or migrating a protocol version — side-by-side HTTP/1.1-vs-2-vs-3 comparison, the step-by-step de-sharding migration, and why Server Push lost to 103 Early Hints. + +### 3. Resource Loading and Critical Rendering Path + +**Core concept:** The browser must build the DOM, CSSOM, and render tree before painting pixels: HTML → DOM → CSSOM → Render Tree → Layout → Paint → Composite. Any resource that blocks this pipeline delays first paint. + +**Why it works:** CSS is render-blocking (no paint until CSSOM is ready) while JavaScript is parser-blocking (`` | +| **Resource hints** | Preload critical fonts, hero images | `` | +| **Image optimization** | Lazy-load below-fold; modern formats | `` | + +See [references/resource-loading.md](references/resource-loading.md) when shaving first paint — the exact async/defer/module execution order, the full resource-hint decision tree, and the image/font (`font-display`, `srcset`, AVIF) playbook. + +### 4. Caching Strategies + +**Core concept:** The fastest network request is one that never happens. Layer caches — browser memory, disk, service worker, CDN, origin — to eliminate round trips for repeat visitors. + +**Why it works:** Cache-Control headers tell the browser and intermediaries exactly how long a response stays valid; content-hashed URLs make aggressive immutable caching safe. Each cache hit eliminates a full network round trip. + +**Key insights:** +- `Cache-Control: no-cache` still caches but revalidates every time; `no-store` never caches — don't confuse them +- `ETag` / `Last-Modified` enable conditional requests (`304 Not Modified`) that skip the body transfer +- Service workers provide a programmable cache layer that works offline (cache-first shell, network-first dynamic content) +- Misconfigured `Vary` headers cause CDN cache pollution — serve the wrong encoding or format to the wrong client + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Static assets** | Immutable cache + hash busting | `style.a1b2c3.css` with `Cache-Control: max-age=31536000, immutable` | +| **HTML documents** | Revalidate on every request | `Cache-Control: no-cache` with `ETag` | +| **API responses** | Short TTL + background refresh | `Cache-Control: max-age=60, stale-while-revalidate=3600` | +| **CDN config** | Cache at edge with correct Vary | `Vary: Accept-Encoding, Accept` | + +See [references/caching-strategies.md](references/caching-strategies.md) when designing a cache policy — the full browser/SW/CDN/origin hierarchy, copy-paste service-worker cache-first vs network-first recipes, and the `Vary` pitfalls that pollute a CDN. + +### 5. Core Web Vitals Optimization + +**Core concept:** Core Web Vitals — LCP, INP, CLS — are Google's user-centric metrics covering loading, interactivity, and visual stability. They impact search ranking and reflect real user experience. + +**Why it works:** A fast TTFB means nothing if the hero image still loads late (LCP) or main-thread JavaScript blocks interactions (INP) — so server-side timing can look green while users wait. Optimize the perceived milestones, not the byte-delivery clock. + +**Key insights** (numeric pass/fail thresholds live in the Quick Diagnostic): +- LCP — optimize the largest visible element (hero image, heading block, video poster) +- INP — keep the main thread free; break long tasks so every interaction (not only the first) stays responsive +- CLS — reserve space for dynamic content before it loads +- TTFB and FCP (< 1.8s) are upstream gates: they bound every downstream milestone, so fix them first +- Measure with Real User Monitoring (RUM) in production — lab/synthetic tests miss real-device and network variance + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **LCP** | Preload LCP element; raise its priority | `` | +| **INP** | Break long tasks; yield to main thread | `scheduler.yield()` or `setTimeout` chunking | +| **CLS** | Reserve space for async content | `` or CSS `aspect-ratio` | +| **Performance budget** | Fail CI when a vital regresses past its Quick Diagnostic threshold | Lighthouse CI assertions on LCP/INP/CLS | + +See [references/core-web-vitals.md](references/core-web-vitals.md) when a metric is in the red — per-metric debugging workflows (what to inspect for a bad LCP/INP/CLS), the lab-vs-RUM tooling map, and per-vital optimization checklists. + +### 6. Real-Time Communication + +**Core concept:** When data must flow continuously, the transport choice — WebSocket, SSE, or long polling — determines latency, resource usage, and scalability. + +**Why it works:** HTTP's request-response model adds overhead to every real-time update. WebSocket offers full-duplex with ~2-byte framing; SSE offers simpler server-to-client push over plain HTTP. Match the transport to the data flow direction and frequency instead of defaulting to the most powerful option. + +**Key insights:** +- WebSocket: bidirectional (chat, gaming, collaborative editing); SSE: server-to-client only, auto-reconnects, proxy-friendly, simpler +- Long polling is a fallback only — high overhead from repeated HTTP requests +- Each WebSocket is a separate TCP connection that bypasses HTTP/2 multiplexing +- Send heartbeat/ping frames — mobile networks silently drop idle connections +- Reconnect with exponential backoff and queue messages while disconnected + +**Code applications:** + +| Context | Pattern | Example | +|---------|---------|---------| +| **Chat / collaboration** | WebSocket + heartbeat + reconnection | `new WebSocket('wss://...')` with ping every 30s | +| **Live feeds / notifications** | SSE for server-to-client streaming | `new EventSource('/api/updates')` | +| **Connection resilience** | Exponential backoff on reconnect | 1s, 2s, 4s, 8s... capped at 30s | +| **Scaling** | Pub/sub broker behind WebSocket servers | Redis Pub/Sub or NATS | + +See [references/real-time-communication.md](references/real-time-communication.md) when building a live feature — the WebSocket connect/heartbeat/reconnect lifecycle, the SSE `EventSource` pattern, and how to scale fan-out behind a pub/sub broker. + +## Common Mistakes + +| Mistake | Why It Fails | Fix | +|---------|-------------|-----| +| Adding bandwidth to fix slow pages | Latency is the bottleneck, not throughput | Reduce round trips: preconnect, cache, CDN | +| Loading all JS upfront | Parser-blocking scripts delay paint and interactivity | Code-split; `defer`; lazy-load non-critical modules | +| No resource hints | Browser discovers critical resources too late | `preconnect` + `preload` for above-fold criticals | +| Missing Cache-Control / `no-store` everywhere | Every visit re-downloads everything | Proper `max-age` + content hashing | +| Ignoring CLS | Layout shifts destroy trust and ranking | Explicit dimensions on images, embeds, ads | +| WebSocket for everything | Needless complexity when SSE/polling suffices | Match transport to data flow; SSE for server push | +| Domain sharding on HTTP/2 | Defeats multiplexing; extra TCP connections | Consolidate origins; let HTTP/2 multiplex | +| No compression | Text resources transfer at full size | Enable Brotli (preferred) or Gzip on server/CDN | + +## Quick Diagnostic + +| Question | If No | Action | +|----------|-------|--------| +| Is TTFB under 800ms? | Server or network too slow | CDN, server caching, check backend | +| Is LCP under 2.5s? | Largest element loads too late | Preload LCP resource; `fetchpriority="high"` | +| Is INP under 200ms? | Main thread blocked | Break long tasks; defer non-critical JS | +| Is CLS under 0.1? | Elements shift after render | Explicit dimensions; reserve space | +| Are static assets content-hashed and cached? | Repeat visitors re-download | Hashed filenames + `Cache-Control: immutable` | +| Is HTTP/2 or HTTP/3 enabled? | No multiplexing or header compression | Enable HTTP/2 on server; HTTP/3 via CDN | +| Are render-blocking resources minimized? | CSS and sync JS delay first paint | Inline critical CSS; `defer` scripts; prune unused CSS | +| Is compression enabled (Brotli/Gzip)? | Uncompressed text transfers | Enable Brotli on server/CDN; Gzip fallback | + +## Further Reading + +Based on Ilya Grigorik's comprehensive guide to browser networking and web performance: + +- [*"High Performance Browser Networking"*](https://www.amazon.com/High-Performance-Browser-Networking-performance/dp/1449344763?tag=wondelai00-20) by Ilya Grigorik (the complete reference for networking protocols, browser internals, and performance optimization) +- [hpbn.co](https://hpbn.co/) -- Free online edition maintained by the author + +## About the Author + +**Ilya Grigorik** is a web performance engineer who spent over a decade at Google working on Chrome, web platform performance, and HTTP standards, and co-chaired the W3C Web Performance Working Group. His book *High Performance Browser Networking* (O'Reilly, 2013) is widely regarded as the definitive reference on how browsers interact with the network. diff --git a/.agents/skills/high-perf-browser/references/caching-strategies.md b/.agents/skills/high-perf-browser/references/caching-strategies.md new file mode 100644 index 00000000..604952fa --- /dev/null +++ b/.agents/skills/high-perf-browser/references/caching-strategies.md @@ -0,0 +1,354 @@ +# Caching Strategies + +The fastest network request is one that never happens. A well-designed caching strategy eliminates redundant data transfer, reduces server load, and dramatically improves load times for repeat visitors and subsequent navigations. + + +## Table of Contents +1. [The Cache Hierarchy](#the-cache-hierarchy) +2. [HTTP Cache-Control Headers](#http-cache-control-headers) +3. [Conditional Requests and Revalidation](#conditional-requests-and-revalidation) +4. [Content Hashing for Cache Busting](#content-hashing-for-cache-busting) +5. [Service Workers for Cache Control](#service-workers-for-cache-control) +6. [CDN Configuration](#cdn-configuration) +7. [Stale-While-Revalidate](#stale-while-revalidate) +8. [Caching Strategy by Resource Type](#caching-strategy-by-resource-type) +9. [Common Caching Mistakes](#common-caching-mistakes) + +--- + +## The Cache Hierarchy + +Browsers check caches in a specific order before making a network request: + +``` +1. Memory cache (in-process, lost on tab close) +2. Service worker cache (programmable, persistent) +3. Disk cache (HTTP cache, persistent) +4. CDN / edge cache (network, shared across users) +5. Origin server (final fallback) +``` + +Each layer closer to the user is faster. Memory cache is near-instant. Disk cache avoids the network entirely. CDN cache reduces RTT by serving from a nearby edge location. The goal is to satisfy as many requests as possible from the closest cache layer. + +## HTTP Cache-Control Headers + +The `Cache-Control` header is the primary mechanism for controlling browser and CDN caching behavior. + +### Essential directives + +| Directive | Meaning | Use case | +|-----------|---------|----------| +| `max-age=N` | Cache for N seconds without revalidation | Static assets with known freshness | +| `no-cache` | Cache but always revalidate before use | HTML documents, API responses | +| `no-store` | Do not cache at all | Sensitive data (banking, health) | +| `immutable` | Never revalidate (even on reload) | Content-hashed static assets | +| `public` | Can be cached by shared caches (CDN) | Public content | +| `private` | Only browser can cache, not CDN | User-specific content | +| `stale-while-revalidate=N` | Serve stale for N seconds while fetching fresh | Near-real-time content | +| `stale-if-error=N` | Serve stale if origin returns an error | Fault tolerance | + +### Common caching patterns + +**Static assets with content hashing (optimal):** +``` +Cache-Control: max-age=31536000, immutable +``` +Files like `app.a1b2c3.js` can be cached forever because the URL changes when content changes. `immutable` tells the browser to skip revalidation even when the user hits refresh. + +**HTML documents:** +``` +Cache-Control: no-cache +``` +The browser caches the document but revalidates on every request. Combined with `ETag`, this enables `304 Not Modified` responses that transfer only headers, not the full document. + +**API responses with near-real-time needs:** +``` +Cache-Control: max-age=0, stale-while-revalidate=60 +``` +Always revalidate, but if the origin is slow, serve the cached response and update in the background. + +**Sensitive content:** +``` +Cache-Control: no-store +``` +Never cache. Use for authentication tokens, financial data, personal health information. + +**Shared public content:** +``` +Cache-Control: public, max-age=3600, stale-while-revalidate=86400 +``` +CDN can cache for 1 hour; serve stale for up to 24 hours while refreshing. + +## Conditional Requests and Revalidation + +When a cached resource expires (or uses `no-cache`), the browser sends a conditional request to check if the resource has changed. + +### ETag (Entity Tag) + +The server generates a unique identifier (hash) for the response content: + +``` +HTTP/1.1 200 OK +ETag: "abc123def456" +Cache-Control: no-cache +``` + +On revalidation, the browser sends: +``` +GET /page.html HTTP/1.1 +If-None-Match: "abc123def456" +``` + +If the content has not changed, the server responds: +``` +HTTP/1.1 304 Not Modified +``` + +No body is transferred -- only headers. This saves bandwidth while ensuring freshness. + +### Last-Modified + +A simpler mechanism using timestamps: + +``` +HTTP/1.1 200 OK +Last-Modified: Wed, 21 Oct 2025 07:28:00 GMT +``` + +Revalidation: +``` +GET /page.html HTTP/1.1 +If-Modified-Since: Wed, 21 Oct 2025 07:28:00 GMT +``` + +**ETag vs. Last-Modified:** ETag is more precise (content-based), while Last-Modified has second-level granularity. Servers should support both; browsers prefer ETag when both are present. + +## Content Hashing for Cache Busting + +The most effective caching pattern combines long-lived cache headers with content-hashed filenames: + +``` +styles.css → styles.a1b2c3.css +app.js → app.d4e5f6.js +logo.png → logo.g7h8i9.png +``` + +**How it works:** +1. Build tools generate a hash of each file's contents +2. The hash is embedded in the filename +3. HTML references the hashed filename +4. The server sets `Cache-Control: max-age=31536000, immutable` +5. When the file changes, a new hash produces a new URL +6. The browser treats it as a completely new resource + +**Implementation with common build tools:** + +Webpack: +```javascript +output: { + filename: '[name].[contenthash].js', + chunkFilename: '[name].[contenthash].js', +} +``` + +Vite: +```javascript +build: { + rollupOptions: { + output: { + entryFileNames: 'assets/[name].[hash].js', + chunkFileNames: 'assets/[name].[hash].js', + assetFileNames: 'assets/[name].[hash].[ext]', + } + } +} +``` + +**The HTML document itself cannot be hashed** (users navigate to `/index.html`, not `/index.a1b2c3.html`). This is why HTML uses `no-cache` while all referenced assets use content hashing. + +## Service Workers for Cache Control + +Service workers provide a programmable cache layer between the browser and the network. They intercept every fetch request and can implement sophisticated caching strategies. + +### Cache-first (offline-first) + +Serve from cache if available; fall back to network: + +```javascript +self.addEventListener('fetch', event => { + event.respondWith( + caches.match(event.request) + .then(cached => cached || fetch(event.request)) + ); +}); +``` + +**Best for:** Static assets (CSS, JS, images, fonts) that rarely change. + +### Network-first + +Try the network; fall back to cache if offline: + +```javascript +self.addEventListener('fetch', event => { + event.respondWith( + fetch(event.request) + .then(response => { + const clone = response.clone(); + caches.open('dynamic').then(cache => cache.put(event.request, clone)); + return response; + }) + .catch(() => caches.match(event.request)) + ); +}); +``` + +**Best for:** HTML documents and API responses where freshness matters. + +### Stale-while-revalidate + +Serve from cache immediately; update cache in the background: + +```javascript +self.addEventListener('fetch', event => { + event.respondWith( + caches.match(event.request).then(cached => { + const fetchPromise = fetch(event.request).then(response => { + const clone = response.clone(); + caches.open('dynamic').then(cache => cache.put(event.request, clone)); + return response; + }); + return cached || fetchPromise; + }) + ); +}); +``` + +**Best for:** Content that updates periodically but where instant display is preferred (news feeds, social timelines). + +### Precaching the app shell + +During service worker installation, cache the core application shell: + +```javascript +const CACHE_NAME = 'app-shell-v1'; +const SHELL_URLS = [ + '/', + '/styles.css', + '/app.js', + '/offline.html', +]; + +self.addEventListener('install', event => { + event.waitUntil( + caches.open(CACHE_NAME) + .then(cache => cache.addAll(SHELL_URLS)) + ); +}); +``` + +### Cache versioning and cleanup + +Old caches must be cleaned up to prevent storage bloat: + +```javascript +self.addEventListener('activate', event => { + event.waitUntil( + caches.keys().then(keys => + Promise.all( + keys + .filter(key => key !== CACHE_NAME) + .map(key => caches.delete(key)) + ) + ) + ); +}); +``` + +## CDN Configuration + +CDNs cache content at edge locations close to users, reducing RTT for cached responses. + +### CDN caching headers + +The `Cache-Control` header controls both browser and CDN caching. Use `s-maxage` to set a different TTL for shared caches (CDNs) vs. browsers: + +``` +Cache-Control: public, max-age=60, s-maxage=3600 +``` + +This tells browsers to cache for 60 seconds but CDNs to cache for 1 hour. + +### Vary header + +The `Vary` header tells caches which request headers affect the response: + +``` +Vary: Accept-Encoding +``` + +Without `Vary: Accept-Encoding`, a CDN might serve a Brotli-compressed response to a client that only supports Gzip. + +Common `Vary` values: +- `Accept-Encoding` -- different compression (Brotli, Gzip, identity) +- `Accept` -- different content types (HTML vs. JSON, AVIF vs. WebP) +- `Accept-Language` -- different language versions + +**Warning:** `Vary: *` or `Vary: Cookie` effectively disables CDN caching because every request differs. + +### Cache purging + +When content changes, CDN caches must be invalidated: + +- **Purge by URL:** Invalidate a specific resource +- **Purge by tag:** Tag resources with categories; purge all resources with a tag +- **Purge by prefix:** Invalidate all resources under a path +- **Soft purge:** Mark as stale; serve stale while fetching fresh (similar to `stale-while-revalidate`) + +Content-hashed URLs largely eliminate the need for cache purging of static assets. Focus purging on HTML and API responses. + +## Stale-While-Revalidate + +The `stale-while-revalidate` directive is one of the most powerful caching tools: + +``` +Cache-Control: max-age=60, stale-while-revalidate=3600 +``` + +Behavior: +1. **0-60 seconds:** Serve from cache without revalidation (fresh) +2. **60-3660 seconds:** Serve from cache immediately (stale) AND fetch a fresh copy in the background +3. **After 3660 seconds:** Cache is completely stale; must wait for network + +This pattern gives users instant responses while keeping content reasonably fresh. It is ideal for: +- API endpoints that update periodically +- Configuration data +- Product listings +- Any content where a few minutes of staleness is acceptable + +## Caching Strategy by Resource Type + +| Resource | Cache-Control | Hash | Revalidation | +|----------|--------------|------|-------------| +| HTML | `no-cache` | No | ETag + 304 | +| CSS (bundled) | `max-age=31536000, immutable` | Yes | None needed | +| JavaScript (bundled) | `max-age=31536000, immutable` | Yes | None needed | +| Images (static) | `max-age=31536000, immutable` | Yes | None needed | +| Fonts | `max-age=31536000, immutable` | Yes | None needed | +| API responses | `max-age=0, stale-while-revalidate=60` | No | ETag + 304 | +| User-specific data | `private, no-cache` | No | ETag + 304 | +| Sensitive data | `no-store` | No | N/A | + +## Common Caching Mistakes + +| Mistake | Consequence | Fix | +|---------|------------|-----| +| No `Cache-Control` on static assets | Browser uses heuristic caching (unpredictable) | Explicitly set `max-age` and `immutable` | +| `no-store` on everything | Every visit fetches all resources from origin | Use `no-cache` for HTML; long cache + hash for assets | +| Missing `Vary: Accept-Encoding` | CDN serves wrong compression format | Add `Vary: Accept-Encoding` to compressed responses | +| Cache busting with query strings | Some CDNs ignore query strings; proxies may not cache | Use filename hashing instead of `?v=123` | +| No ETag on HTML | Conditional requests impossible; full document re-downloaded | Configure server to generate ETags | +| `max-age=0` without `stale-while-revalidate` | Every request blocks on revalidation | Add `stale-while-revalidate` for better perceived performance | +| Service worker caching everything | Cache grows unbounded; stale content persists | Implement cache limits and versioned cleanup | + +A comprehensive caching strategy is often the single highest-impact performance optimization -- it reduces server load, saves bandwidth, and makes repeat visits feel instant. diff --git a/.agents/skills/high-perf-browser/references/core-web-vitals.md b/.agents/skills/high-perf-browser/references/core-web-vitals.md new file mode 100644 index 00000000..87de4f52 --- /dev/null +++ b/.agents/skills/high-perf-browser/references/core-web-vitals.md @@ -0,0 +1,446 @@ +# Core Web Vitals Optimization + +Core Web Vitals are Google's standardized performance metrics that measure real user experience. They directly impact search ranking and correlate strongly with user engagement, conversion rates, and bounce rates. + + +## Table of Contents +1. [The Three Core Web Vitals](#the-three-core-web-vitals) +2. [LCP: Largest Contentful Paint](#lcp-largest-contentful-paint) +3. [INP: Interaction to Next Paint](#inp-interaction-to-next-paint) +4. [CLS: Cumulative Layout Shift](#cls-cumulative-layout-shift) +5. [Measuring Core Web Vitals](#measuring-core-web-vitals) +6. [Performance Budgets](#performance-budgets) +7. [Debugging Workflow](#debugging-workflow) +8. [Quick Reference: Optimization Impact](#quick-reference-optimization-impact) + +--- + +## The Three Core Web Vitals + +| Metric | Measures | Good | Needs Improvement | Poor | +|--------|----------|------|-------------------|------| +| **LCP** (Largest Contentful Paint) | Loading performance | < 2.5s | 2.5s - 4.0s | > 4.0s | +| **INP** (Interaction to Next Paint) | Interactivity | < 200ms | 200ms - 500ms | > 500ms | +| **CLS** (Cumulative Layout Shift) | Visual stability | < 0.1 | 0.1 - 0.25 | > 0.25 | + +### Supporting metrics + +| Metric | Measures | Target | +|--------|----------|--------| +| **TTFB** (Time to First Byte) | Server responsiveness | < 800ms | +| **FCP** (First Contentful Paint) | Initial render speed | < 1.8s | +| **TBT** (Total Blocking Time) | Main thread availability (lab proxy for INP) | < 200ms | + +## LCP: Largest Contentful Paint + +LCP measures when the largest visible content element finishes rendering. This is what users perceive as "the page has loaded." + +### What counts as the LCP element + +- `` elements (including those inside ``) +- `